@astryxdesign/native 0.7.6-canary.eae5d92 → 0.7.6-canary.eae71cb
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.
- package/apple/Package.swift +0 -2
- package/apple/README.md +6 -3
- package/package.json +3 -3
- package/apple/Sources/Astryx/Avatar/Avatar.spec.md +0 -219
- package/apple/Sources/Astryx/Avatar/AvatarStatusDot.spec.md +0 -162
- package/apple/Sources/Astryx/Button/Button.spec.md +0 -174
- package/apple/Sources/Astryx/Icon/Icon.spec.md +0 -189
- package/apple/Sources/Astryx/TextInput/TextInput.spec.md +0 -179
- package/apple/Sources/Astryx/Thumbnail/Thumbnail.spec.md +0 -191
package/apple/Package.swift
CHANGED
|
@@ -27,8 +27,6 @@ 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", "Button/Button.spec.md", "Icon/Icon.spec.md", "TextInput/TextInput.spec.md", "Thumbnail/Thumbnail.spec.md"],
|
|
32
30
|
resources: [.process("Resources")]
|
|
33
31
|
),
|
|
34
32
|
.testTarget(name: "AstryxNativeTests", dependencies: ["AstryxNative"], path: "Tests/AstryxNativeTests"),
|
package/apple/README.md
CHANGED
|
@@ -26,13 +26,13 @@ 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
|
-
│ │ ├── Icon/ # Icon
|
|
30
|
-
│ │ ├── Avatar/ # Avatar
|
|
29
|
+
│ │ ├── Icon/ # Icon
|
|
30
|
+
│ │ ├── Avatar/ # Avatar
|
|
31
31
|
│ │ ├── Text/ # Text
|
|
32
32
|
│ │ ├── Heading/ # Heading
|
|
33
33
|
│ │ ├── Button/ # Button
|
|
34
34
|
│ │ ├── TextInput/ # TextInput
|
|
35
|
-
│ │ ├── Thumbnail/ # Thumbnail
|
|
35
|
+
│ │ ├── Thumbnail/ # Thumbnail
|
|
36
36
|
│ │ ├── Card/ # Card
|
|
37
37
|
│ │ └── Banner/ # Banner
|
|
38
38
|
│ └── AstryxNative/ # contracts, wire, logic host (module AstryxNative)
|
|
@@ -46,6 +46,9 @@ apple/
|
|
|
46
46
|
└── Tests/
|
|
47
47
|
```
|
|
48
48
|
|
|
49
|
+
Each component's Swift spec sits beside its core spec, at
|
|
50
|
+
`docs/specs/components/<ComponentRoot>/<Name>.swift.spec.md`.
|
|
51
|
+
|
|
49
52
|
- **`Sources/Astryx/<Name>/`** holds one folder per component, named as in
|
|
50
53
|
`packages/core/src/<Name>/`. Each view has core's component name in the
|
|
51
54
|
`Astryx` module (`Button`, `Text`), which re-exports SwiftUI and the
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@astryxdesign/native",
|
|
3
|
-
"version": "0.7.6-canary.
|
|
3
|
+
"version": "0.7.6-canary.eae71cb",
|
|
4
4
|
"description": "Experimental native platforms for Astryx (iOS, Android, macOS, Windows) — published to npm only under the @canary dist-tag; never released as a stable (latest) version.",
|
|
5
5
|
"author": "Meta Open Source",
|
|
6
6
|
"license": "MIT",
|
|
@@ -70,10 +70,10 @@
|
|
|
70
70
|
}
|
|
71
71
|
},
|
|
72
72
|
"peerDependencies": {
|
|
73
|
-
"@astryxdesign/core": "0.7.6-canary.
|
|
73
|
+
"@astryxdesign/core": "0.7.6-canary.eae71cb"
|
|
74
74
|
},
|
|
75
75
|
"devDependencies": {
|
|
76
|
-
"@astryxdesign/core": "0.7.6-canary.
|
|
76
|
+
"@astryxdesign/core": "0.7.6-canary.eae71cb"
|
|
77
77
|
},
|
|
78
78
|
"scripts": {
|
|
79
79
|
"build": "node ../../scripts/clean-dist.mjs && tsc --project tsconfig.build.json && node scripts/generate.mjs --types",
|
|
@@ -1,219 +0,0 @@
|
|
|
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.
|
|
@@ -1,162 +0,0 @@
|
|
|
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.
|
|
@@ -1,174 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
schema_version: 3
|
|
3
|
-
template_version: 7
|
|
4
|
-
kind: component
|
|
5
|
-
id: component:swift/Button
|
|
6
|
-
platform_of: component:Button
|
|
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: [packages/native/apple/Tests/AstryxTests/ButtonTests.swift]
|
|
15
|
-
modules: []
|
|
16
|
-
families: [family:buttons, family:navigation-destinations]
|
|
17
|
-
design_specs: []
|
|
18
|
-
architecture: [architecture:public-component-api]
|
|
19
|
-
contributing: []
|
|
20
|
-
system_specs: [spec:AST-082, spec:AST-093]
|
|
21
|
-
---
|
|
22
|
-
|
|
23
|
-
# Button (Swift) component contract
|
|
24
|
-
|
|
25
|
-
## Contract at a glance
|
|
26
|
-
|
|
27
|
-
| Area | Contract |
|
|
28
|
-
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
29
|
-
| Public contract | `Button(label:variant:size:elevation:isLoading:isInterruptible:isDisabled:width:tooltip:href:base:onClick:)` and `Button(_ props: ButtonProps)`, a SwiftUI `View` in module `Astryx`. |
|
|
30
|
-
| Behavior | A SwiftUI `Button` drawn with the Astryx button style, or a SwiftUI `Link` when an enabled Button has `href`. While loading, a spinner covers the label, which keeps its place, and presses wait unless it is interruptible. |
|
|
31
|
-
| End-user impact | A person gets one action control whose width holds while it loads and which never runs twice by accident; a link Button stays a link while busy, so VoiceOver and keyboard focus stay on it. |
|
|
32
|
-
| Builder impact | An app passes core's Button props; `href` makes the same view open a destination through the system. |
|
|
33
|
-
| Compatibility/readiness | Breaking for canary callers: `action:`, `fillsWidth:`, `icon:`, and the hand-written `AstryxButtonVariant` and `AstryxButtonSize` give way to the generated `ButtonProps` (`onClick:`, `width:`, `ButtonVariant`, `ButtonSize`). Draft; built and tested on macOS and the iOS Simulator. |
|
|
34
|
-
| Review checks | Reject a loading link that swaps to a button, a loading Button that runs `onClick` or opens its link while not interruptible, a size change while loading, or a disabled Button with `href` that opens. |
|
|
35
|
-
| Governing rules | `component:Button` FR7–FR11; `spec:AST-082` FR3; `spec:AST-093` FR1–FR5; the Swift component API record (A2–A5) under `packages/native/specs/swift/library/`. |
|
|
36
|
-
|
|
37
|
-
This table is a review projection; the body below is authoritative.
|
|
38
|
-
|
|
39
|
-
## Intent
|
|
40
|
-
|
|
41
|
-
Button on Apple platforms is core's action control drawn with SwiftUI's own
|
|
42
|
-
button and link, so presses, focus, and VoiceOver work the platform's way while
|
|
43
|
-
its look, loading, and link behavior follow the core `Button` contract.
|
|
44
|
-
|
|
45
|
-
## Compatibility and migration
|
|
46
|
-
|
|
47
|
-
- Released default preserved: `not yet released`
|
|
48
|
-
- Compatibility class: breaking for canary callers (hand-written parameters → generated `ButtonProps`)
|
|
49
|
-
- Controlled/uncontrolled behavior: not applicable
|
|
50
|
-
- Migration decision: none
|
|
51
|
-
|
|
52
|
-
Consumer migration instructions belong in consumer docs and release notes.
|
|
53
|
-
|
|
54
|
-
## Ownership boundary
|
|
55
|
-
|
|
56
|
-
**Owns**
|
|
57
|
-
|
|
58
|
-
- How Swift draws core's Button: the SwiftUI control it uses, the loading
|
|
59
|
-
presentation, when presses land, and when `href` makes it a link.
|
|
60
|
-
|
|
61
|
-
**Does not own / non-goals**
|
|
62
|
-
|
|
63
|
-
- The meaning of Button's props, its variants and sizes, and its pending and
|
|
64
|
-
disabled states — owned by `component:Button`.
|
|
65
|
-
- Which destinations a link may open — owned by
|
|
66
|
-
`family:navigation-destinations`.
|
|
67
|
-
- How a prop switches to a different SwiftUI control in general — owned by the
|
|
68
|
-
Swift component API record (A2).
|
|
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
|
-
| control | button; link | a SwiftUI `Button`, or a SwiftUI `Link` for an enabled `href` | always | button | `component:swift/Button` | experimental | an `href` that is not a URL leaves a button |
|
|
75
|
-
| loading | idle; loading | `isLoading`: spinner over the label, presses wait | always | idle | `component:Button` | experimental | none |
|
|
76
|
-
| interruptible | off; on | `isInterruptible`: presses and link opens land while loading | while loading | off | `component:Button` | experimental | none |
|
|
77
|
-
| availability | operable; busy-only; disabled | disabled wins over loading | always | operable | `component:Button` | experimental | none |
|
|
78
|
-
|
|
79
|
-
## Behavioral and layout contract
|
|
80
|
-
|
|
81
|
-
| ID | Candidate invariant | Basis | Draft review state |
|
|
82
|
-
| --- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- | ------------------ |
|
|
83
|
-
| FR1 | Both initializers MUST build the same `ButtonProps`; base props (`id`, `isHidden`) come through `ButtonProps`. | Swift component API A2, A3 | verify |
|
|
84
|
-
| FR2 | While loading, the view MUST draw a spinner over the label, keep the label's place so its size does not change, stay at full opacity, and read as busy ("Loading", core's catalog message) to VoiceOver. It MUST NOT run `onClick` while loading unless it is interruptible; an interruptible loading Button runs `onClick` on each press. | `component:Button` FR7–FR9 | verify |
|
|
85
|
-
| FR3 | An enabled Button with `href` MUST draw a SwiftUI `Link` to that destination, in the Astryx button style, which VoiceOver reads as a link. A disabled Button with `href` MUST draw its disabled button, which never opens. | `component:Button` FR11; `spec:AST-082` FR3 | verify |
|
|
86
|
-
| FR4 | A loading Button with `href` MUST stay a `Link`: it keeps focus, shows its spinner, reads as busy, and does not open its destination until loading ends, unless the Button is interruptible, in which case each activation opens it. It never swaps to a button while busy. | `component:Button` FR9 ("a link-mode Button stays a link while busy-only"), FR11 | verify |
|
|
87
|
-
| FR5 | A Button whose `href` is a script URL (`javascript:`, `vbscript:`) or an HTML document in a `data:` URL MUST NOT open it, after core's normalization (control characters removed, whitespace trimmed, the scheme compared in lowercase without spaces after its colon): it draws its enabled button, which runs `onClick` and does not look disabled. | `component:Button` FR11; `family:navigation-destinations` | verify |
|
|
88
|
-
| FR6 | A disabled Button MUST keep its keyboard focus stop and show its tooltip on focus, draw its disabled look, read as a dimmed button to VoiceOver, and never run `onClick`; a focused Button that becomes disabled keeps one view structure and its focus. A Button with `href` keeps its `Link` and its disabled button in one structure, and focus moves from the link to the button when it becomes disabled, and back when it is enabled, so focus stays inside the component. | `component:Button` FR10; `family:buttons` FR3 | verify |
|
|
89
|
-
|
|
90
|
-
### Allowed variation
|
|
91
|
-
|
|
92
|
-
- **AV1 — Platform controls.** The control is SwiftUI's `Button` or `Link`, so
|
|
93
|
-
focus rings, press feedback, and how the system opens a destination are the
|
|
94
|
-
platform's own.
|
|
95
|
-
|
|
96
|
-
### Representative states
|
|
97
|
-
|
|
98
|
-
| State | Required invariant | Allowed variation |
|
|
99
|
-
| ------------------------- | ---------------------------------------------- | ----------------------- |
|
|
100
|
-
| loading | same size as idle; spinner; busy; presses wait | spinner is the system's |
|
|
101
|
-
| loading and interruptible | presses land | none |
|
|
102
|
-
| enabled with `href` | a `Link` | none |
|
|
103
|
-
| disabled with `href` | a dimmed button that never opens | none |
|
|
104
|
-
| loading with `href` | a `Link` that does not open until loading ends | none |
|
|
105
|
-
|
|
106
|
-
### Transformation and precedence order
|
|
107
|
-
|
|
108
|
-
- **ORD1 — Availability.** Disabled, then loading (busy-only unless
|
|
109
|
-
interruptible), then operable, as in core.
|
|
110
|
-
|
|
111
|
-
### Performance and resources
|
|
112
|
-
|
|
113
|
-
- **PR1 — No work while idle.** The view holds no timers or tasks; loading is a
|
|
114
|
-
prop the caller sets.
|
|
115
|
-
|
|
116
|
-
## Accessibility contract
|
|
117
|
-
|
|
118
|
-
- **AR1 — Name and state.** The label names the control in every state; a
|
|
119
|
-
loading Button adds core's "Loading" message as its value and announces it
|
|
120
|
-
when loading starts. A link Button reads as a link, a disabled one as dimmed.
|
|
121
|
-
- **AR2 — Rendered tree not measured.** Tests assert what the view sets; the
|
|
122
|
-
rendered accessibility tree is not measured until an app-hosted target exists.
|
|
123
|
-
|
|
124
|
-
## Design relationships
|
|
125
|
-
|
|
126
|
-
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|
|
127
|
-
| ---------------- | ------------------------------- | -------------------------- | -------------- | ------------------ |
|
|
128
|
-
| Spinner | the system's activity indicator | prescribed by the platform | supporting | FR2, FR4 |
|
|
129
|
-
|
|
130
|
-
The component implements design requirements without copying their rationale.
|
|
131
|
-
|
|
132
|
-
Platform control: SwiftUI `Button` and `Link` with `ProgressView`; they are the
|
|
133
|
-
platform's own controls and satisfy the contract (`spec:AST-093` FR2). A
|
|
134
|
-
`tooltip` shows through the shared Astryx tooltip (`library/tooltip.spec.md`).
|
|
135
|
-
Guideline pages: Buttons, Progress indicators, and Accessibility in the Apple
|
|
136
|
-
Human Interface Guidelines (`spec:AST-093` FR3).
|
|
137
|
-
|
|
138
|
-
Theme values read (`spec:AST-093` FR4): `color.accent`, `color.onAccent`,
|
|
139
|
-
`color.error`, `color.onError`, `color.neutral`, `color.textPrimary`,
|
|
140
|
-
`size.elementSm`, `size.elementMd`, `size.elementLg`, `radius.element`,
|
|
141
|
-
`space` steps for padding, `font.label` and `font.family.body`, the
|
|
142
|
-
`shadow.low`, `shadow.med`, and `shadow.high` layers, and the Dynamic Type
|
|
143
|
-
scale.
|
|
144
|
-
|
|
145
|
-
## Family and system relationships
|
|
146
|
-
|
|
147
|
-
- `component:Button` owns the props, the pending and disabled states, and link
|
|
148
|
-
mode; this record states only how Swift draws them.
|
|
149
|
-
- `family:navigation-destinations` owns destination handling for links.
|
|
150
|
-
|
|
151
|
-
## Verification map
|
|
152
|
-
|
|
153
|
-
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|
|
154
|
-
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ----------------------------- |
|
|
155
|
-
| FR1 | `ButtonTests.swift` initializer test | both initializers | differing props fail | `audit:swift/Button/api` |
|
|
156
|
-
| FR2 | `ButtonTests.swift` loading, width, and interruptible tests | loading; loading and interruptible | a press that lands while loading, a size change, or dimming fails | `audit:swift/Button/loading` |
|
|
157
|
-
| FR3 | `ButtonTests.swift` `href` test | enabled and disabled with `href` | a disabled Button that opens, or an enabled one that is not a link, fails | `audit:swift/Button/link` |
|
|
158
|
-
| FR4 | `ButtonTests.swift` `href` test with loading, and with loading and interruptible | loading with `href`; interruptible | a busy link that swaps to a button or opens before loading ends fails | `audit:swift/Button/link` |
|
|
159
|
-
| FR5 | `ButtonTests.swift` refused-destination and normalization tests | `javascript:`, `vbscript:`, `data:text/html`, padded, mixed case, with controls, and `data: text/html`; a `data:image` and a `mailto:` that still open | a refused destination that opens, an unnormalized one that slips through, or a refused one that looks disabled, fails | `audit:swift/Button/link` |
|
|
160
|
-
| FR6 | `ButtonTests.swift` disabled tests, including a disabled Button with `href` keeping its destination for one structure; the focus stop and the focus move are not measured until an app-hosted test can observe them | disabled with and without a tooltip; disabled with `href` | a disabled Button that runs `onClick` or opens its link, or one marked without its focus stop, fails | `audit:swift/Button/disabled` |
|
|
161
|
-
| AR1 | `ButtonTests.swift` accessibility assertions | idle; loading; link | a missing name, value, or announcement fails | `audit:swift/Button/a11y` |
|
|
162
|
-
|
|
163
|
-
## Decision log
|
|
164
|
-
|
|
165
|
-
No component-local decision is recorded.
|
|
166
|
-
|
|
167
|
-
## Open questions
|
|
168
|
-
|
|
169
|
-
None.
|
|
170
|
-
|
|
171
|
-
## Content boundary
|
|
172
|
-
|
|
173
|
-
This file does not duplicate consumer prop tables/examples, current audit
|
|
174
|
-
results, implementation steps, or family/system rules. It links to their owners.
|
|
@@ -1,189 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
schema_version: 3
|
|
3
|
-
template_version: 7
|
|
4
|
-
kind: component
|
|
5
|
-
id: component:swift/Icon
|
|
6
|
-
platform_of: component:Icon
|
|
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/IconTests.swift,
|
|
17
|
-
packages/native/src/contract/contracts.test.ts,
|
|
18
|
-
]
|
|
19
|
-
modules: []
|
|
20
|
-
families: []
|
|
21
|
-
design_specs: []
|
|
22
|
-
architecture:
|
|
23
|
-
[
|
|
24
|
-
architecture:component-size-cascade,
|
|
25
|
-
architecture:icon-resolution-and-component-slots,
|
|
26
|
-
]
|
|
27
|
-
contributing: []
|
|
28
|
-
system_specs: [spec:AST-082, spec:AST-093]
|
|
29
|
-
---
|
|
30
|
-
|
|
31
|
-
# Icon (Swift) component contract
|
|
32
|
-
|
|
33
|
-
## Contract at a glance
|
|
34
|
-
|
|
35
|
-
| Area | Contract |
|
|
36
|
-
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
37
|
-
| Public contract | `Icon(_ icon: IconName, color: IconColor? = nil, size: IconSize? = nil, label: String? = nil)` and `Icon(_ props: IconProps)`, a SwiftUI `View` in module `Astryx`. `IconName` is a string-backed name with every built-in name as a static member (`.search`, `.close`). |
|
|
38
|
-
| Behavior | Draws the image the theme or the platform maps the name to (an SF Symbol, or an asset the app ships), in a square box at core's icon size grown with Dynamic Type, in core's icon color token or the surrounding foreground. A name nothing maps, or an asset the app does not ship, draws nothing. |
|
|
39
|
-
| End-user impact | A person sees the platform's own symbol for each shared icon, or the app's own artwork where its theme maps one, sized and colored as on the web, and VoiceOver reads only icons that carry a label. |
|
|
40
|
-
| Builder impact | An app passes a shared name (`.search`) or a name it maps in its theme (`"acme:rocket"`). An SVG component, which the web also accepts, has no Swift form. |
|
|
41
|
-
| Compatibility/readiness | Additive: a new view and a new generated `IconName` type. Draft; built and tested on macOS and the iOS Simulator; device captures are attached to the change. |
|
|
42
|
-
| Review checks | Reject a substitute symbol for an unknown name, an image or attributed-text form of the icon slot, a visual parameter beyond the contract, an unlabeled icon that VoiceOver reads, or an owner's size winning over an explicit `size`. |
|
|
43
|
-
| Governing rules | `spec:AST-082` FR4, FR7, FR17; `spec:AST-093` FR1–FR5; the Swift component API, styles, slots, theme environment, and accessibility records under `packages/native/specs/swift/library/`. |
|
|
44
|
-
|
|
45
|
-
This table is a review projection; the body below is authoritative.
|
|
46
|
-
|
|
47
|
-
## Intent
|
|
48
|
-
|
|
49
|
-
Icon on Apple platforms draws Astryx's shared icon names as SF Symbols, or as
|
|
50
|
-
images the app ships where its theme maps them, so an
|
|
51
|
-
icon beside system controls looks like the platform's own while its size, color,
|
|
52
|
-
and accessibility follow the core `Icon` contract.
|
|
53
|
-
|
|
54
|
-
## Compatibility and migration
|
|
55
|
-
|
|
56
|
-
- Released default preserved: `not yet released`
|
|
57
|
-
- Compatibility class: additive
|
|
58
|
-
- Controlled/uncontrolled behavior: not applicable
|
|
59
|
-
- Migration decision: none
|
|
60
|
-
|
|
61
|
-
Consumer migration instructions belong in consumer docs and release notes.
|
|
62
|
-
|
|
63
|
-
## Ownership boundary
|
|
64
|
-
|
|
65
|
-
**Owns**
|
|
66
|
-
|
|
67
|
-
- Resolving a shared icon name to an image: the theme's mapping (an SF Symbol
|
|
68
|
-
or an app asset), else the platform's default SF Symbol.
|
|
69
|
-
- Drawing the image in a square box at core's icon size, grown with Dynamic
|
|
70
|
-
Type, in core's icon color token. An asset takes the color token when its
|
|
71
|
-
asset catalog renders it as a template image, and keeps its own colors when
|
|
72
|
-
it renders as an original image.
|
|
73
|
-
- The icon's VoiceOver exposure.
|
|
74
|
-
|
|
75
|
-
**Does not own / non-goals**
|
|
76
|
-
|
|
77
|
-
- The meaning of `icon`, `color`, `size`, and `label` and the built-in names —
|
|
78
|
-
owned by `component:Icon` and `spec:AST-082` FR17.
|
|
79
|
-
- Which size an owner gives the icons in its icon slot — owned by each owning
|
|
80
|
-
component and `architecture:component-size-cascade`.
|
|
81
|
-
- The default SF Symbol for each name — owned by `@astryxdesign/native`'s icon
|
|
82
|
-
defaults, which a test keeps equal to the Swift map.
|
|
83
|
-
|
|
84
|
-
## Public concepts
|
|
85
|
-
|
|
86
|
-
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|
|
87
|
-
| ------------- | ----------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | ----------------------------------------- | -------------------------- | ---------------------- | ------------ | ----------------------------------------------------------------------- |
|
|
88
|
-
| icon name | the built-in names; a `<library>:<name>` the theme maps | `IconName`, a string on the wire, with each built-in as a static member | always | required | `component:Icon` | experimental | an unmapped name stops a development build and draws nothing in release |
|
|
89
|
-
| symbol source | theme mapping; platform default | `Theme(icons:)` replaces a built-in or registers a library name with an SF Symbol or an app asset | always | platform default | `component:swift/Icon` | experimental | a theme entry wins over the default |
|
|
90
|
-
| size | `xsm`, `sm`, `md`, `lg`; unset | 12, 16, 20, 24 points at the default text size | always | owner's icon size, else md | `component:Icon` | experimental | unset takes the owner's size, then `md` |
|
|
91
|
-
| color | `primary`, `secondary`, `tertiary`, `disabled`, `accent`, `info`, `success`, `error`, `warning`, `inherit`; unset | core's icon color tokens; `inherit` keeps the surrounding foreground | always | `inherit` | `component:Icon` | experimental | unset is `inherit` |
|
|
92
|
-
|
|
93
|
-
## Behavioral and layout contract
|
|
94
|
-
|
|
95
|
-
| ID | Candidate invariant | Basis | Draft review state |
|
|
96
|
-
| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------ |
|
|
97
|
-
| FR1 | The view MUST draw the image the theme's `icons` maps the name to, an SF Symbol or an asset the app ships, else the platform default for a built-in name. A name neither maps, or an asset the app does not ship, MUST stop a development build with a message naming it and draw nothing in a release build, never a substitute. | `spec:AST-082` FR17; Swift slots S2 | verify |
|
|
98
|
-
| FR2 | The symbol MUST fit a square box whose side is core's size in points (12, 16, 20, 24 for `xsm`, `sm`, `md`, `lg`), multiplied by the Dynamic Type scale the theme environment reads. | core `Icon` sizes; `spec:AST-093` FR3; theme environment E1 | verify |
|
|
99
|
-
| FR3 | The view MUST use its own `size`, else the size its owning component gives icons in its documented icon slot, else `md`. | `architecture:component-size-cascade`; Swift slots S4 | verify |
|
|
100
|
-
| FR4 | The view MUST draw in core's token for its `color` — primary and secondary icon tokens, the secondary icon token for `tertiary`, the disabled icon token, the accent color, and the `info`, `success`, `error`, and `warning` status icon roles — and, for `inherit` or no color, MUST keep the surrounding foreground style. | core `Icon` color map; `spec:AST-093` FR4 | verify |
|
|
101
|
-
| FR5 | Both initializers MUST build the same `IconProps`; the labeled initializer takes the contract's props with the generated types and defaults, and base props (`id`, `isHidden`) come through `IconProps`. With `isHidden` the view draws nothing; `id` becomes the accessibility identifier. | Swift component API A2, A3, A7; `spec:AST-082` FR7 | verify |
|
|
102
|
-
|
|
103
|
-
### Allowed variation
|
|
104
|
-
|
|
105
|
-
- **AV1 — Glyph shape.** The glyph is the platform's SF Symbol, not the web's
|
|
106
|
-
SVG; a theme may map any name to another SF Symbol or to an image the app
|
|
107
|
-
ships (`spec:AST-082` FR17).
|
|
108
|
-
|
|
109
|
-
### Representative states
|
|
110
|
-
|
|
111
|
-
| State | Required invariant | Allowed variation |
|
|
112
|
-
| --------------------------- | --------------------------------------------- | ---------------------------- |
|
|
113
|
-
| every size | box side 12, 16, 20, 24 points at Large text | glyph proportions per symbol |
|
|
114
|
-
| every color, light and dark | the color's token in the current mode | none |
|
|
115
|
-
| inside an owner's icon slot | the owner's size unless the icon sets its own | none |
|
|
116
|
-
| largest text size | the box grows with Dynamic Type | none |
|
|
117
|
-
| labeled and unlabeled | VoiceOver reads only the labeled icon | none |
|
|
118
|
-
|
|
119
|
-
### Transformation and precedence order
|
|
120
|
-
|
|
121
|
-
- **ORD1 — Image.** Theme mapping (SF Symbol or app asset) → platform default
|
|
122
|
-
SF Symbol → nothing.
|
|
123
|
-
- **ORD2 — Size.** Explicit `size` → owner's icon size → `md`, then × Dynamic
|
|
124
|
-
Type scale.
|
|
125
|
-
|
|
126
|
-
### Performance and resources
|
|
127
|
-
|
|
128
|
-
- **PR1 — No image data of its own.** The view draws a system symbol by name,
|
|
129
|
-
or an asset from the app's main bundle by name; it holds no image data and
|
|
130
|
-
loads nothing from the network.
|
|
131
|
-
|
|
132
|
-
## Accessibility contract
|
|
133
|
-
|
|
134
|
-
- **AR1 — Decorative unless labeled.** With no `label`, or an empty one, the
|
|
135
|
-
view is hidden from VoiceOver. With a label, it is one image element named by
|
|
136
|
-
the label, keeping SwiftUI's image trait and adding none (`spec:AST-082` FR17;
|
|
137
|
-
Swift accessibility X1, X4).
|
|
138
|
-
In an avatar's status slot a labeled icon also names the status, which joins
|
|
139
|
-
the avatar's name (`component:swift/Avatar` AR6).
|
|
140
|
-
- **AR2 — Rendered tree not measured.** Tests assert what the view sets; the
|
|
141
|
-
rendered accessibility tree is not measured until an app-hosted target exists.
|
|
142
|
-
|
|
143
|
-
## Design relationships
|
|
144
|
-
|
|
145
|
-
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|
|
146
|
-
| ---------------- | -------------------------------------------------------------- | -------------------------- | -------------- | ------------------ |
|
|
147
|
-
| Glyph | SF Symbols (Apple Human Interface Guidelines), or an app asset | prescribed by the platform | supporting | FR1, FR2 |
|
|
148
|
-
|
|
149
|
-
The component implements design requirements without copying their rationale.
|
|
150
|
-
|
|
151
|
-
Platform control: SwiftUI `Image(systemName:)`, or `Image(_:bundle:)` for an
|
|
152
|
-
app asset. It is the platform's own icon view and satisfies the contract, so no custom drawing is needed (`spec:AST-093`
|
|
153
|
-
FR2). Guideline pages: SF Symbols and Accessibility in the Apple Human
|
|
154
|
-
Interface Guidelines.
|
|
155
|
-
|
|
156
|
-
Theme values read: `color.iconPrimary`, `color.iconSecondary`,
|
|
157
|
-
`color.iconDisabled`, `color.accent`, `color.iconInfo`, `color.iconSuccess`,
|
|
158
|
-
`color.iconError`, `color.iconWarning`, the theme's `icons` map, and the
|
|
159
|
-
Dynamic Type scale.
|
|
160
|
-
|
|
161
|
-
## Family and system relationships
|
|
162
|
-
|
|
163
|
-
- `component:Icon` owns the props, the built-in names, the size scale, and the
|
|
164
|
-
color map; this record states only how Swift draws them.
|
|
165
|
-
- `architecture:component-size-cascade` owns when an owner's icon size applies;
|
|
166
|
-
owners set it through an internal environment value this view reads.
|
|
167
|
-
|
|
168
|
-
## Verification map
|
|
169
|
-
|
|
170
|
-
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|
|
171
|
-
| -------- | ------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | -------------------------- |
|
|
172
|
-
| FR1 | `IconTests.swift` symbol and asset tests (a test bundle stands in for the app's); `contracts.test.ts` IconName test | every built-in; theme replacement; library name; a shipped asset; a missing asset drawing nothing and reported (the release-build path) | a missing default, a symbol absent on the platform, a missing asset that draws or goes unreported, or a substitute fails | `audit:swift/Icon/symbols` |
|
|
173
|
-
| FR2, FR3 | `IconTests.swift` size and Dynamic Type renders | each size; owner size; explicit size; AX5 | a wrong side or an owner size beating an explicit size fails | `audit:swift/Icon/size` |
|
|
174
|
-
| FR4 | `IconTests.swift` color map and two-theme render | every color; neutral and butter | a wrong token or a color of the view's own fails | `audit:swift/Icon/color` |
|
|
175
|
-
| FR5 | `IconTests.swift` initializer and hidden tests | both initializers; `isHidden` | differing props or a drawn hidden icon fails | `audit:swift/Icon/api` |
|
|
176
|
-
| AR1 | `IconTests.swift` accessibility assertions | labeled, unlabeled, empty label | an unlabeled icon with a label, or a labeled one without, fails | `audit:swift/Icon/a11y` |
|
|
177
|
-
|
|
178
|
-
## Decision log
|
|
179
|
-
|
|
180
|
-
No component-local decision is recorded.
|
|
181
|
-
|
|
182
|
-
## Open questions
|
|
183
|
-
|
|
184
|
-
None.
|
|
185
|
-
|
|
186
|
-
## Content boundary
|
|
187
|
-
|
|
188
|
-
This file does not duplicate consumer prop tables/examples, current audit
|
|
189
|
-
results, implementation steps, or family/system rules. It links to their owners.
|
|
@@ -1,179 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
schema_version: 3
|
|
3
|
-
template_version: 7
|
|
4
|
-
kind: component
|
|
5
|
-
id: component:swift/TextInput
|
|
6
|
-
platform_of: component:TextInput
|
|
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: [packages/native/apple/Tests/AstryxTests/TextInputTests.swift]
|
|
15
|
-
modules: []
|
|
16
|
-
families: [family:input-fields]
|
|
17
|
-
design_specs: []
|
|
18
|
-
architecture: [architecture:public-component-api]
|
|
19
|
-
contributing: []
|
|
20
|
-
system_specs: [spec:AST-082, spec:AST-093, spec:AST-085]
|
|
21
|
-
---
|
|
22
|
-
|
|
23
|
-
# TextInput (Swift) component contract
|
|
24
|
-
|
|
25
|
-
## Contract at a glance
|
|
26
|
-
|
|
27
|
-
| Area | Contract |
|
|
28
|
-
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
29
|
-
| Public contract | `TextInput(label:value:type:onChange:size:isLabelHidden:description:isOptional:isRequired:onEnter:isDisabled:isReadOnly:disabledMessage:isLoading:placeholder:labelTooltip:status:statusVariant:hasClear:hasAutoFocus:base:)` and `TextInput(_ props: TextInputProps)`, a SwiftUI `View` in module `Astryx`. |
|
|
30
|
-
| Behavior | An editable field is SwiftUI's `TextField`, or `SecureField` for a password. A read-only or disabled field draws its value, keeps a focus stop without raising a keyboard, and reads to VoiceOver as SwiftUI's text field. |
|
|
31
|
-
| End-user impact | A person types in the platform's own field; keyboard users still reach a read-only or disabled field and its reason; VoiceOver users hear the name, any error, the description, and the state. |
|
|
32
|
-
| Builder impact | An app passes `value` and `onChange` as the contract types them, not a `Binding`. |
|
|
33
|
-
| Compatibility/readiness | Breaking for canary callers: a `Binding` gives way to `value` and `onChange`, as the contract types them. Draft; built and tested on macOS and the iOS Simulator. |
|
|
34
|
-
| Review checks | Reject a read-only field that raises a keyboard or accepts edits, a disabled field that leaves focus, a read-only password that shows its characters, an error only in the hint, or `.help` for a tip. |
|
|
35
|
-
| Governing rules | `component:TextInput` FR3–FR10, FR13, FR15; `family:input-fields` FR4; `spec:AST-085`; `spec:AST-082` FR3, FR7, FR11; `spec:AST-093` FR1–FR5; the Swift component API, tooltip, and accessibility records under `packages/native/specs/swift/library/`. |
|
|
36
|
-
|
|
37
|
-
This table is a review projection; the body below is authoritative.
|
|
38
|
-
|
|
39
|
-
## Intent
|
|
40
|
-
|
|
41
|
-
TextInput on Apple platforms is core's text field drawn with SwiftUI's own
|
|
42
|
-
field for typing, so input methods, autofill, and the keyboard work the
|
|
43
|
-
platform's way, while its read-only and disabled states keep core's focus and
|
|
44
|
-
reading behavior where SwiftUI's field cannot.
|
|
45
|
-
|
|
46
|
-
## Compatibility and migration
|
|
47
|
-
|
|
48
|
-
- Released default preserved: `not yet released`
|
|
49
|
-
- Compatibility class: breaking for canary callers (`Binding` → `value` and `onChange`)
|
|
50
|
-
- Controlled/uncontrolled behavior: controlled; `value` and `onChange` only
|
|
51
|
-
- Migration decision: none
|
|
52
|
-
|
|
53
|
-
Consumer migration instructions belong in consumer docs and release notes.
|
|
54
|
-
|
|
55
|
-
## Ownership boundary
|
|
56
|
-
|
|
57
|
-
**Owns**
|
|
58
|
-
|
|
59
|
-
- Which platform field Swift uses in each state, how a read-only or disabled
|
|
60
|
-
field keeps focus and reads to VoiceOver, and its status announcements.
|
|
61
|
-
|
|
62
|
-
**Does not own / non-goals**
|
|
63
|
-
|
|
64
|
-
- The meaning of TextInput's props and states — owned by `component:TextInput`
|
|
65
|
-
and `family:input-fields`.
|
|
66
|
-
- Tooltip behavior — owned by the Swift tooltip record.
|
|
67
|
-
|
|
68
|
-
## Public concepts
|
|
69
|
-
|
|
70
|
-
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|
|
71
|
-
| ------------ | ----------------------------- | ------------------------------------------------------------------------ | ----------------------------------------- | -------- | --------------------------- | ------------ | ---------------------- |
|
|
72
|
-
| field | editable; drawn | SwiftUI `TextField`/`SecureField`, or the drawn read-only/disabled field | always | editable | `component:swift/TextInput` | experimental | none |
|
|
73
|
-
| availability | editable; read-only; disabled | disabled wins over read-only | always | editable | `component:TextInput` | experimental | none |
|
|
74
|
-
|
|
75
|
-
## Behavioral and layout contract
|
|
76
|
-
|
|
77
|
-
| ID | Candidate invariant | Basis | Draft review state |
|
|
78
|
-
| --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------- | ------------------ |
|
|
79
|
-
| FR1 | Both initializers MUST build the same `TextInputProps`. Edits reach `onChange` only while the field is editable; Return runs `onEnter` while editable or read-only. | Swift component API A2, A3, A5; `component:TextInput` FR3, FR10 | verify |
|
|
80
|
-
| FR2 | A read-only or disabled field MUST draw its value (masked for a password, the placeholder when empty), keep its focus stop without raising a keyboard (a field that becomes read-only or disabled while focused keeps focus: the editable and drawn parts stay in one view structure and focus moves between them), accept no edits, and read to VoiceOver as SwiftUI's text field (`accessibilityRepresentation`): dimmed when disabled, a secure field for a password, with "Read only" or the disabled reason in its description. | `component:TextInput` FR6, FR8; `spec:AST-085`; `family:input-fields` FR4; AV1 | verify |
|
|
81
|
-
| FR3 | An error MUST be in the field's VoiceOver label after its name; the description and status message MUST stay readable as text and in the description. A status message, and "Loading", are announced on the field's first appearance and when they change, an error at high priority. | `component:TextInput` FR4, FR9; `component:FieldStatus` AR1 | verify |
|
|
82
|
-
| FR4 | The label tip, the tooltip-variant status, the clear button, and a disabled reason MUST show through the shared Astryx tooltip; no view uses `.help`. The tooltip-variant status tip is a button, as core's status icon is, named by its status and speaking its message when VoiceOver activates it. Trailing controls each lay out across their own 44-point target. | `component:TextInput` FR5, FR7, FR15; `spec:AST-082` FR11; Swift tooltip record | verify |
|
|
83
|
-
| FR5 | Base `id` and `isHidden` MUST apply to the field control, TextInput's base target: `id` is its accessibility identifier, and `isHidden` takes the control and its buttons out of layout and focus (autofocus included) while the label, description, and status stay, with the label and its note read by VoiceOver as text. | `component:TextInput` FR13; `spec:AST-082` FR7 | verify |
|
|
84
|
-
|
|
85
|
-
### Allowed variation
|
|
86
|
-
|
|
87
|
-
- **AV1 — The drawn read-only and disabled field.** No platform field fits
|
|
88
|
-
both states on both platforms, so Swift draws the value and gives VoiceOver
|
|
89
|
-
SwiftUI's text field in its place. Fields considered:
|
|
90
|
-
- SwiftUI `TextField` and `SecureField`: no read-only mode, and `.disabled`
|
|
91
|
-
removes the focus stop core keeps (`spec:AST-085`).
|
|
92
|
-
- UIKit `UITextField` refusing edits through its delegate: focus raises the
|
|
93
|
-
keyboard unless its input view is replaced, its text and colors must be
|
|
94
|
-
bridged from the theme by hand, and SwiftUI's image renderer and previews
|
|
95
|
-
do not draw it.
|
|
96
|
-
- AppKit `NSTextField` with editing off and selection on: a true read-only
|
|
97
|
-
field on macOS, with no iOS counterpart, so the two platforms would differ.
|
|
98
|
-
|
|
99
|
-
### Representative states
|
|
100
|
-
|
|
101
|
-
| State | Required invariant | Allowed variation |
|
|
102
|
-
| ------------------ | ----------------------------------------------------------- | ----------------- |
|
|
103
|
-
| editable | the platform field; edits reach `onChange` | none |
|
|
104
|
-
| read-only | value shown; focus stop; no keyboard; Return runs `onEnter` | none |
|
|
105
|
-
| read-only password | masked; not selectable | none |
|
|
106
|
-
| disabled | dimmed; focus stop; reads as a dimmed text field | none |
|
|
107
|
-
| error | error in the label; message readable | none |
|
|
108
|
-
|
|
109
|
-
### Transformation and precedence order
|
|
110
|
-
|
|
111
|
-
- **ORD1 — Availability.** Disabled, then read-only, then editable, as in core.
|
|
112
|
-
|
|
113
|
-
### Performance and resources
|
|
114
|
-
|
|
115
|
-
- **PR1 — No work while idle.** The view holds no timers; announcements fire
|
|
116
|
-
only on first appearance or a change.
|
|
117
|
-
|
|
118
|
-
## Accessibility contract
|
|
119
|
-
|
|
120
|
-
- **AR1 — Name, error, description.** The name is the label and its note; an
|
|
121
|
-
error follows it in the label; the description, other status messages,
|
|
122
|
-
"Read only", and the disabled reason are the description.
|
|
123
|
-
- **AR2 — Rendered tree not measured.** Tests assert what the view sets; the
|
|
124
|
-
rendered accessibility tree and keyboard focus are not measured until an
|
|
125
|
-
app-hosted target exists.
|
|
126
|
-
|
|
127
|
-
## Design relationships
|
|
128
|
-
|
|
129
|
-
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|
|
130
|
-
| ---------------- | ------------------------- | -------------------------- | -------------- | ------------------ |
|
|
131
|
-
| Field | the platform's text field | prescribed by the platform | primary | FR1, FR2 |
|
|
132
|
-
|
|
133
|
-
The component implements design requirements without copying their rationale.
|
|
134
|
-
|
|
135
|
-
Platform control: SwiftUI `TextField` and `SecureField` for editing; the drawn
|
|
136
|
-
field in AV1 for read-only and disabled (`spec:AST-093` FR2). Guideline pages:
|
|
137
|
-
Text fields and Accessibility in the Apple Human Interface Guidelines
|
|
138
|
-
(`spec:AST-093` FR3).
|
|
139
|
-
|
|
140
|
-
Theme values read (`spec:AST-093` FR4): `color.textPrimary`,
|
|
141
|
-
`color.textSecondary`, `color.textDisabled`, `color.borderEmphasized`, the
|
|
142
|
-
status roles `architecture:theme-tokens` INV11 assigns (`color.borderError`,
|
|
143
|
-
`color.borderWarning`, `color.borderSuccess` for the border;
|
|
144
|
-
`color.iconError`, `color.iconWarning`, `color.iconSuccess` for the icon;
|
|
145
|
-
`color.errorMuted`, `color.warningMuted`, `color.successMuted` for the
|
|
146
|
-
message ground and `color.onErrorMuted`, `color.onWarningMuted`,
|
|
147
|
-
`color.onSuccessMuted` for its text),
|
|
148
|
-
`size.elementSm`, `size.elementMd`, `size.elementLg`, `size.borderWidth`,
|
|
149
|
-
`radius.element`, `space` steps, `font.body`, `font.label`, `font.supporting`,
|
|
150
|
-
`font.weight.medium`, `font.weight.normal`,
|
|
151
|
-
`font.family.body`, the theme's icons, and the Dynamic Type scale.
|
|
152
|
-
|
|
153
|
-
## Family and system relationships
|
|
154
|
-
|
|
155
|
-
- `component:TextInput` and `family:input-fields` own the props and states;
|
|
156
|
-
this record states only how Swift draws them.
|
|
157
|
-
|
|
158
|
-
## Verification map
|
|
159
|
-
|
|
160
|
-
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|
|
161
|
-
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------ |
|
|
162
|
-
| FR1 | `TextInputTests.swift` initializer and edit tests | both initializers; editable, read-only, disabled | differing props, or an edit that reaches `onChange` while not editable, fails | `audit:swift/TextInput/api` |
|
|
163
|
-
| FR2 | `TextInputTests.swift` read-only, password, placeholder, and focus-stop tests, and the VoiceOver field each state gives `accessibilityRepresentation` (text or secure, dimmed when disabled, label, value, and description); the rendered tree and focus are not measured | read-only; read-only password; empty; disabled; disabled password; error | a shown password, a missing placeholder, a secure field read as text, an undimmed disabled field, or a disabled field without a stop fails | `audit:swift/TextInput/states` |
|
|
164
|
-
| FR3 | `TextInputTests.swift` label, description, and announcement tests | error with and without a message; warning; type change | an error missing from the label, or a missed announcement change, fails | `audit:swift/TextInput/a11y` |
|
|
165
|
-
| FR4 | `TooltipPresenterTests.swift` `.help` guard; `TextInputTests.swift` checks the row ends in buttons and that the status tip is a button named by its status with its message; overlap of the 44-point targets is not measured until an app-hosted test can hit-test them | clear and tooltip status together; tooltip, attached, and detached statuses | `.help` in a view, or a status tip without the button trait, fails | `audit:swift/TextInput/tips` |
|
|
166
|
-
| FR5 | `TextInputTests.swift` base tests: `isHidden` leaves the control out of layout; `id` and the control base target; the identifier on the drawn control is not measured until an app-hosted test exists | `id`; `isHidden` | `isHidden` keeping the control in layout or hiding the label fails | `audit:swift/TextInput/base` |
|
|
167
|
-
|
|
168
|
-
## Decision log
|
|
169
|
-
|
|
170
|
-
No component-local decision is recorded.
|
|
171
|
-
|
|
172
|
-
## Open questions
|
|
173
|
-
|
|
174
|
-
None.
|
|
175
|
-
|
|
176
|
-
## Content boundary
|
|
177
|
-
|
|
178
|
-
This file does not duplicate consumer prop tables/examples, current audit
|
|
179
|
-
results, implementation steps, or family/system rules. It links to their owners.
|
|
@@ -1,191 +0,0 @@
|
|
|
1
|
-
---
|
|
2
|
-
schema_version: 3
|
|
3
|
-
template_version: 7
|
|
4
|
-
kind: component
|
|
5
|
-
id: component:swift/Thumbnail
|
|
6
|
-
platform_of: component:Thumbnail
|
|
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/ThumbnailTests.swift,
|
|
17
|
-
packages/native/src/contract/contracts.test.ts,
|
|
18
|
-
packages/native/src/theme/swiftIOSStrings.test.ts,
|
|
19
|
-
]
|
|
20
|
-
modules: []
|
|
21
|
-
families: []
|
|
22
|
-
design_specs: []
|
|
23
|
-
architecture: []
|
|
24
|
-
contributing: []
|
|
25
|
-
system_specs: [spec:AST-082, spec:AST-093]
|
|
26
|
-
---
|
|
27
|
-
|
|
28
|
-
# Thumbnail (Swift) component contract
|
|
29
|
-
|
|
30
|
-
## Contract at a glance
|
|
31
|
-
|
|
32
|
-
| Area | Contract |
|
|
33
|
-
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|
|
34
|
-
| Public contract | `Thumbnail(src:, alt:, label:, isLoading:, isDisabled:, showRemoveOn:, onClick:, onRemove:)` and `Thumbnail(_ props: ThumbnailProps)`, a SwiftUI `View` in module `Astryx`. |
|
|
35
|
-
| Behavior | A 64-point square on the theme's neutral plate showing the image, else a placeholder silhouette; a skeleton while loading with no image and an upload look over one; a remove button in the top trailing corner; a tap that opens the thumbnail. |
|
|
36
|
-
| End-user impact | A person attaching images on iPhone sees the same previews as on the web, can open or remove each one, and VoiceOver reads each by its file name and description and announces once when an upload starts. |
|
|
37
|
-
| Builder impact | An app passes the image URL, a label such as a file name, and the actions it supports. A single trailing closure is `onClick`. |
|
|
38
|
-
| Compatibility/readiness | Additive: a new view, generated `ThumbnailProps`, and four of core's messages in the Swift string catalogs. Draft; built and tested on macOS and the iOS Simulator; device captures are attached to the change. |
|
|
39
|
-
| Review checks | Reject a hidden remove button on a touch device, a tap or remove that works while disabled, a tap that works while loading, an unnamed thumbnail, an upload announced on every render, or a color that is not a theme token. |
|
|
40
|
-
| Governing rules | `spec:AST-082` FR3, FR7; `spec:AST-086` FR8; `spec:AST-093` FR1–FR5; the Swift component API, theme environment, and accessibility (X1, X3, X4, X6, X7) records under `packages/native/specs/swift/library/`. |
|
|
41
|
-
|
|
42
|
-
This table is a review projection; the body below is authoritative.
|
|
43
|
-
|
|
44
|
-
## Intent
|
|
45
|
-
|
|
46
|
-
Thumbnail on Apple platforms is core's preview of an image attachment, drawn
|
|
47
|
-
with SwiftUI's own image loading, progress view, and buttons.
|
|
48
|
-
|
|
49
|
-
## Compatibility and migration
|
|
50
|
-
|
|
51
|
-
- Released default preserved: `not yet released`
|
|
52
|
-
- Compatibility class: additive
|
|
53
|
-
- Controlled/uncontrolled behavior: not applicable
|
|
54
|
-
- Migration decision: none
|
|
55
|
-
|
|
56
|
-
Consumer migration instructions belong in consumer docs and release notes.
|
|
57
|
-
|
|
58
|
-
## Ownership boundary
|
|
59
|
-
|
|
60
|
-
**Owns**
|
|
61
|
-
|
|
62
|
-
- The 64-point tile, its image, placeholder, skeleton, and upload look.
|
|
63
|
-
- The remove button, its visibility, and the open tap.
|
|
64
|
-
- The thumbnail's names and its upload announcement.
|
|
65
|
-
|
|
66
|
-
**Does not own / non-goals**
|
|
67
|
-
|
|
68
|
-
- The meaning of the props and the words — owned by `component:Thumbnail` and
|
|
69
|
-
core's message catalogs.
|
|
70
|
-
- Laying out several thumbnails, which belongs to the screen that holds them.
|
|
71
|
-
|
|
72
|
-
## Public concepts
|
|
73
|
-
|
|
74
|
-
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|
|
75
|
-
| ------------ | ------------------------------------ | -------------------------------------------------------------------------- | ----------------------------------------- | -------- | --------------------- | ------------ | ------------------------------------ |
|
|
76
|
-
| picture | image, placeholder, skeleton, upload | what the tile shows | always | — | `component:Thumbnail` | experimental | a failed image shows the placeholder |
|
|
77
|
-
| showRemoveOn | `hover`, `always` | `hover` shows remove under a pointer and always on touch; `always` at rest | with `onRemove` | `hover` | `component:Thumbnail` | experimental | none |
|
|
78
|
-
| name | label and alt, label, alt, fallback | what VoiceOver reads for the thumbnail | always | fallback | `component:Thumbnail` | experimental | blank strings count as absent |
|
|
79
|
-
|
|
80
|
-
## Behavioral and layout contract
|
|
81
|
-
|
|
82
|
-
| ID | Candidate invariant | Basis | Draft review state |
|
|
83
|
-
| --- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------ | ------------------ |
|
|
84
|
-
| FR1 | The tile MUST be 64 by 64 points, clipped to `radius.element`, on `color.neutral`. It MUST show the image at `src` cropped to fill the tile, with a 1-point `color.border` inset edge on all four sides of the tile; with no `src`, or when the image fails, a 24-point image silhouette in `color.iconSecondary`. | core `Thumbnail` styles | verify |
|
|
85
|
-
| FR2 | `isLoading` with no `src` MUST show a skeleton in `color.skeleton` at 25% opacity; after 1 second it climbs to 92.5% in ten equal held steps over core's default 550 ms medium duration and back, repeating, as core's does, and it rests at 25% under Reduce Motion; under Increase Contrast its color moves 30% toward `color.textPrimary`, as core's does under `prefers-contrast: more`. `isLoading` with a `src` MUST draw `color.overlay` over the image with the platform's small progress view in `color.onDark`, which keeps its size at any text size. | core `Thumbnail`; Swift accessibility X6 | verify |
|
|
86
|
-
| FR3 | With `onRemove`, a 20-point remove button MUST sit `space.s1` from the top trailing corner on `color.overlay` with the shared `close` `Icon` at `xsm` in `color.onDark`, which the theme can remap and which keeps its size at any text size. It is visible at rest with `always` and on touch devices; with `hover` under a pointer, it appears while the pointer is over an enabled thumbnail or while its open or remove button has keyboard focus; a pointer reveals nothing on a disabled thumbnail, as core turns pointer events off there. | core `Thumbnail` `showRemoveOn`; `spec:AST-082` FR3 | verify |
|
|
87
|
-
| FR4 | With `onClick`, not disabled, and not loading, the tile MUST be a SwiftUI `Button` that paints `color.overlayPressed` while pressed. `isDisabled` MUST draw the thumbnail at half opacity and turn off its tap and remove button. The open button while loading or disabled, and the remove button while disabled, MUST stay mounted but inert, so focus on them stays put and VoiceOver reads them dimmed (`spec:AST-085`; Swift accessibility X2); during an upload the remove button stays active, as core's does. | core `Thumbnail` | verify |
|
|
88
|
-
| FR5 | With a `label`, the thumbnail MUST show it through the Astryx tooltip (`architecture:native-swift-library-tooltip`), as core's tooltip wraps the whole thumbnail: not a tab stop itself, keyboard focus on its open or remove button shows the label, and a direct tap opens it while an open action still runs, as the Tooltip by input table below states. A disabled thumbnail shows none, and the label is not a hint, since it is in the thumbnail's name. | core `Thumbnail` `label`; core `Tooltip`; `spec:AST-082` FR3 | verify |
|
|
89
|
-
| FR6 | Both initializers MUST build the same `ThumbnailProps`; a single trailing closure is `onClick`. Base props come through `ThumbnailProps`: with `isHidden` the view draws nothing; `id` becomes the accessibility identifier. | Swift component API A2–A4, A7; `spec:AST-082` FR7 | verify |
|
|
90
|
-
|
|
91
|
-
**Tooltip by input (FR5).** The Astryx tooltip's rules apply; this table
|
|
92
|
-
states Thumbnail's choices.
|
|
93
|
-
|
|
94
|
-
| Input | With a `label` | Disabled, or no `label` |
|
|
95
|
-
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
|
|
96
|
-
| Pointer | the bubble shows the label above the tile after 200 ms, stays while the pointer is on it, and a press hides it | nothing |
|
|
97
|
-
| Keyboard focus | the label at once when keyboard focus is on the open or remove button, as focus within core's tooltip wrapper shows it; the thumbnail itself is not a tab stop | nothing |
|
|
98
|
-
| Touch tap | a direct tap opens the bubble with the label, while an open action and an enclosing row still run; another tap on it, or a tap anywhere else, closes it, and that tap still reaches what it lands on | nothing |
|
|
99
|
-
| VoiceOver | the label is read once, in the thumbnail's name; the bubble is hidden and the tap is left alone | nothing |
|
|
100
|
-
|
|
101
|
-
### Allowed variation
|
|
102
|
-
|
|
103
|
-
- **AV1 — Glyphs and spinner.** The placeholder is the SF Symbol `photo.fill`
|
|
104
|
-
and the spinner the platform's progress view.
|
|
105
|
-
|
|
106
|
-
### Representative states
|
|
107
|
-
|
|
108
|
-
| State | Required invariant | Allowed variation |
|
|
109
|
-
| ------------------------------ | --------------------------------------------- | ----------------- |
|
|
110
|
-
| image | the image fills the tile with an inset edge | image content |
|
|
111
|
-
| no image, failed image | the placeholder silhouette | AV1 |
|
|
112
|
-
| loading without and with image | skeleton; upload overlay with a progress view | AV1 |
|
|
113
|
-
| remove, hover and always | visible on touch; at rest with `always` | none |
|
|
114
|
-
| tappable, disabled | a button; dimmed with no tap or remove | none |
|
|
115
|
-
| light and dark, two themes | each theme's colors | none |
|
|
116
|
-
|
|
117
|
-
### Transformation and precedence order
|
|
118
|
-
|
|
119
|
-
- **ORD1 — Picture.** Skeleton (loading, no `src`) → image → placeholder.
|
|
120
|
-
- **ORD2 — Name.** `label — alt` → `label` → `alt` → core's fallback word.
|
|
121
|
-
|
|
122
|
-
### Performance and resources
|
|
123
|
-
|
|
124
|
-
- **PR1 — System loading.** Images load through `AsyncImage` and the system
|
|
125
|
-
URL cache.
|
|
126
|
-
|
|
127
|
-
## Accessibility contract
|
|
128
|
-
|
|
129
|
-
- **AR1 — Named group.** The thumbnail is a container named by ORD2. The image
|
|
130
|
-
reads as its `alt` and is hidden without one (X4). With `onClick` the open
|
|
131
|
-
button covers the image and its name, "Open" with the thumbnail's name,
|
|
132
|
-
stands for it, so VoiceOver does not read the image on its own, as core's
|
|
133
|
-
open button wraps the image and a button's content is presentational.
|
|
134
|
-
- **AR2 — Named actions.** The open button reads "Open" with the name and the
|
|
135
|
-
remove button "Remove" with the name, from core's message catalogs in the
|
|
136
|
-
person's language (X1).
|
|
137
|
-
- **AR3 — Upload announced once.** Each upload start, including one already
|
|
138
|
-
in progress when the thumbnail appears, announces core's "Loading" once, as
|
|
139
|
-
core does; the spinner is hidden (`spec:AST-086` FR8; X3).
|
|
140
|
-
- **AR4 — Targets.** The remove button answers taps across 44 by 44 points
|
|
141
|
-
without moving its drawing (X7).
|
|
142
|
-
- **AR5 — Rendered tree not measured.** Tests assert what the view sets; the
|
|
143
|
-
rendered accessibility tree, the hit region, and the announcement are not
|
|
144
|
-
measured until an app-hosted target exists.
|
|
145
|
-
|
|
146
|
-
## Design relationships
|
|
147
|
-
|
|
148
|
-
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|
|
149
|
-
| ---------------- | ---------------------------------------- | ------------------------ | -------------- | ------------------ |
|
|
150
|
-
| Image, overlays | Apple Human Interface Guidelines, Images | prescribed by core | supporting | FR1–FR4 |
|
|
151
|
-
|
|
152
|
-
The component implements design requirements without copying their rationale.
|
|
153
|
-
|
|
154
|
-
Platform controls: SwiftUI `AsyncImage` for the image, `ProgressView` for the
|
|
155
|
-
upload spinner, and `Button` for the open tap and remove action
|
|
156
|
-
(`spec:AST-093` FR2). SwiftUI has no thumbnail control, so the tile and its
|
|
157
|
-
overlays are drawn here. Guideline pages: Images, Progress indicators, Buttons,
|
|
158
|
-
and Accessibility in the Apple Human Interface Guidelines.
|
|
159
|
-
|
|
160
|
-
Theme values read: `color.neutral`, `color.border`, `color.iconSecondary`,
|
|
161
|
-
`color.overlay`, `color.onDark`, `color.overlayPressed`, `radius.element`,
|
|
162
|
-
`space.s1`, `color.skeleton`, `color.textPrimary`, the theme's `close` icon, Reduce Motion, and Increase Contrast; and, for the Astryx tooltip's bubble, `color.textPrimary`, `color.backgroundSurface`, `space.s1`, `space.s2`, `radius.container`, and the body text size and weight.
|
|
163
|
-
|
|
164
|
-
## Family and system relationships
|
|
165
|
-
|
|
166
|
-
- `component:Thumbnail` owns the props, the words, and the look; this record
|
|
167
|
-
states only how Swift draws them.
|
|
168
|
-
|
|
169
|
-
## Verification map
|
|
170
|
-
|
|
171
|
-
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|
|
172
|
-
| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
|
|
173
|
-
| FR1 | `ThumbnailTests.swift` size, plate, and two-theme renders | no image; default, neutral, butter; the largest text size | a wrong size or a color of its own fails | `audit:swift/Thumbnail/tile` |
|
|
174
|
-
| FR2 | `ThumbnailTests.swift` loading states, skeleton color, contrast mix, and largest-text render | loading with and without `src`; Increase Contrast; the largest text size | a skeleton over an image, no upload look, a wrong skeleton color, or a tile that grows fails | `audit:swift/Thumbnail/loading` |
|
|
175
|
-
| FR3, FR4 | `ThumbnailTests.swift` remove, tap, disabled, and mounted-while-inert tests and render | `always`, `hover`; disabled; loading | a hidden remove on touch or under keyboard focus, a hard-coded remove glyph, or a tap while disabled or loading fails; an open or remove button that unmounts while loading or disabled fails; a pointer that reveals the remove button on a disabled thumbnail fails | `audit:swift/Thumbnail/actions` |
|
|
176
|
-
| FR5 | `TooltipPresenterTests.swift` for each input; `ThumbnailTests.swift` name and focus-within tests | enabled and disabled; blank label | a tooltip on a disabled thumbnail, or none for keyboard focus on its open or remove button, fails; that the tile keeps one structure across a disabled toggle or an upload ending is not measured, since a test cannot see a rebuild | `audit:swift/Thumbnail/tooltip` |
|
|
177
|
-
| FR6 | `ThumbnailTests.swift` initializer, trailing-closure, and hidden tests; `contracts.test.ts` | both initializers; `isHidden` | differing props or a drawn hidden thumbnail fails | `audit:swift/Thumbnail/api` |
|
|
178
|
-
| AR1, AR2 | `ThumbnailTests.swift` name and open-button tests (`hasOpenButton` decides the image's hiding); `swiftIOSStrings.test.ts`; the rendered tree is not measured | label and alt, each alone, neither; with and without `onClick` | a wrong name or a missing catalog message fails | `audit:swift/Thumbnail/a11y` |
|
|
179
|
-
|
|
180
|
-
## Decision log
|
|
181
|
-
|
|
182
|
-
No component-local decision is recorded.
|
|
183
|
-
|
|
184
|
-
## Open questions
|
|
185
|
-
|
|
186
|
-
None.
|
|
187
|
-
|
|
188
|
-
## Content boundary
|
|
189
|
-
|
|
190
|
-
This file does not duplicate consumer prop tables/examples, current audit
|
|
191
|
-
results, implementation steps, or family/system rules. It links to their owners.
|