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