@astryxdesign/native 0.7.5-canary.7380888 → 0.7.5-canary.79a7a90

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (138) hide show
  1. package/README.md +46 -24
  2. package/apple/Package.swift +27 -4
  3. package/apple/README.md +204 -0
  4. package/apple/Sources/Astryx/Avatar/Avatar.spec.md +210 -0
  5. package/apple/Sources/Astryx/Avatar/Avatar.swift +418 -0
  6. package/apple/Sources/Astryx/Banner/Banner.swift +80 -0
  7. package/apple/Sources/Astryx/Base/BaseProps.swift +16 -0
  8. package/apple/Sources/Astryx/Button/Button.swift +168 -0
  9. package/apple/Sources/Astryx/Card/Card.swift +109 -0
  10. package/apple/Sources/Astryx/Exports.swift +8 -0
  11. package/apple/Sources/Astryx/Heading/Heading.swift +117 -0
  12. package/apple/Sources/Astryx/Icon/Icon.spec.md +187 -0
  13. package/apple/Sources/Astryx/Icon/Icon.swift +156 -0
  14. package/apple/Sources/Astryx/Localization/AstryxStrings.swift +22 -0
  15. package/apple/Sources/Astryx/Resources/af.lproj/Localizable.strings +4 -0
  16. package/apple/Sources/Astryx/Resources/ar.lproj/Localizable.strings +4 -0
  17. package/apple/Sources/Astryx/Resources/ca.lproj/Localizable.strings +4 -0
  18. package/apple/Sources/Astryx/Resources/cs.lproj/Localizable.strings +4 -0
  19. package/apple/Sources/Astryx/Resources/da.lproj/Localizable.strings +4 -0
  20. package/apple/Sources/Astryx/Resources/de.lproj/Localizable.strings +4 -0
  21. package/apple/Sources/Astryx/Resources/el.lproj/Localizable.strings +4 -0
  22. package/apple/Sources/Astryx/Resources/en.lproj/Localizable.strings +4 -0
  23. package/apple/Sources/Astryx/Resources/es.lproj/Localizable.strings +4 -0
  24. package/apple/Sources/Astryx/Resources/fi.lproj/Localizable.strings +4 -0
  25. package/apple/Sources/Astryx/Resources/fr.lproj/Localizable.strings +4 -0
  26. package/apple/Sources/Astryx/Resources/he.lproj/Localizable.strings +4 -0
  27. package/apple/Sources/Astryx/Resources/hu.lproj/Localizable.strings +4 -0
  28. package/apple/Sources/Astryx/Resources/it.lproj/Localizable.strings +4 -0
  29. package/apple/Sources/Astryx/Resources/ja.lproj/Localizable.strings +4 -0
  30. package/apple/Sources/Astryx/Resources/ko.lproj/Localizable.strings +4 -0
  31. package/apple/Sources/Astryx/Resources/nb.lproj/Localizable.strings +4 -0
  32. package/apple/Sources/Astryx/Resources/nl.lproj/Localizable.strings +4 -0
  33. package/apple/Sources/Astryx/Resources/pl.lproj/Localizable.strings +4 -0
  34. package/apple/Sources/Astryx/Resources/pt-BR.lproj/Localizable.strings +4 -0
  35. package/apple/Sources/Astryx/Resources/pt-PT.lproj/Localizable.strings +4 -0
  36. package/apple/Sources/Astryx/Resources/ro.lproj/Localizable.strings +4 -0
  37. package/apple/Sources/Astryx/Resources/ru.lproj/Localizable.strings +4 -0
  38. package/apple/Sources/Astryx/Resources/sr.lproj/Localizable.strings +4 -0
  39. package/apple/Sources/Astryx/Resources/sv.lproj/Localizable.strings +4 -0
  40. package/apple/Sources/Astryx/Resources/tr.lproj/Localizable.strings +4 -0
  41. package/apple/Sources/Astryx/Resources/uk.lproj/Localizable.strings +4 -0
  42. package/apple/Sources/Astryx/Resources/vi.lproj/Localizable.strings +4 -0
  43. package/apple/Sources/Astryx/Resources/zh-Hans.lproj/Localizable.strings +4 -0
  44. package/apple/Sources/Astryx/Resources/zh-Hant.lproj/Localizable.strings +4 -0
  45. package/apple/Sources/Astryx/Text/Text.swift +102 -0
  46. package/apple/Sources/Astryx/Text/TypeStyle.swift +143 -0
  47. package/apple/Sources/Astryx/TextInput/TextInput.swift +81 -0
  48. package/apple/Sources/Astryx/Theme/AstryxIcons.swift +108 -0
  49. package/apple/Sources/Astryx/Theme/Generated/ButterTheme.swift +477 -0
  50. package/apple/Sources/Astryx/Theme/Generated/ChocolateTheme.swift +477 -0
  51. package/apple/Sources/Astryx/Theme/Generated/DefaultTheme.swift +477 -0
  52. package/apple/Sources/Astryx/Theme/Generated/GothicTheme.swift +477 -0
  53. package/apple/Sources/Astryx/Theme/Generated/MatchaTheme.swift +477 -0
  54. package/apple/Sources/Astryx/Theme/Generated/NeutralTheme.swift +477 -0
  55. package/apple/Sources/Astryx/Theme/Generated/StoneTheme.swift +477 -0
  56. package/apple/Sources/Astryx/Theme/Generated/Tokens.swift +1413 -0
  57. package/apple/Sources/Astryx/Theme/Generated/Y2kTheme.swift +477 -0
  58. package/apple/Sources/Astryx/Theme/Shadow.swift +41 -0
  59. package/apple/Sources/Astryx/Theme/Theme.swift +318 -0
  60. package/apple/Sources/Astryx/Tooltip/TooltipPresenter.swift +551 -0
  61. package/apple/Sources/Astryx/Wire/AstryxNodeView.swift +77 -0
  62. package/apple/Sources/AstryxNative/Generated/AstryxNode.swift +9 -0
  63. package/apple/Sources/AstryxNative/Generated/Avatar.swift +163 -0
  64. package/apple/Sources/AstryxNative/Generated/Badge.swift +89 -0
  65. package/apple/Sources/AstryxNative/Generated/Button.swift +14 -2
  66. package/apple/Sources/AstryxNative/Generated/Icon.swift +107 -0
  67. package/apple/Sources/AstryxNative/Generated/IconName.swift +47 -0
  68. package/apple/Sources/AstryxNative/Generated/Switch.swift +2 -26
  69. package/apple/Sources/AstryxNative/Logic/AstryxLogicHost.swift +102 -0
  70. package/apple/Tests/AstryxNativeTests/ControlPropsTests.swift +2 -0
  71. package/apple/Tests/AstryxNativeTests/LogicHostTests.swift +85 -0
  72. package/apple/Tests/AstryxTests/AvatarTests.swift +263 -0
  73. package/apple/Tests/AstryxTests/BannerTests.swift +47 -0
  74. package/apple/Tests/AstryxTests/ButtonTests.swift +72 -0
  75. package/apple/Tests/AstryxTests/CardTests.swift +159 -0
  76. package/apple/Tests/AstryxTests/EnvironmentTests.swift +177 -0
  77. package/apple/Tests/AstryxTests/HeadingTests.swift +68 -0
  78. package/apple/Tests/AstryxTests/IconTests.swift +189 -0
  79. package/apple/Tests/AstryxTests/NamesTests.swift +28 -0
  80. package/apple/Tests/AstryxTests/Pixels.swift +68 -0
  81. package/apple/Tests/AstryxTests/Resources/astryx-test-icon.png +0 -0
  82. package/apple/Tests/AstryxTests/StringsTests.swift +23 -0
  83. package/apple/Tests/AstryxTests/TextInputTests.swift +29 -0
  84. package/apple/Tests/AstryxTests/TextTests.swift +109 -0
  85. package/apple/Tests/AstryxTests/ThemeTests.swift +39 -0
  86. package/apple/Tests/AstryxTests/TooltipPresenterTests.swift +220 -0
  87. package/apple/Tests/AstryxTests/TwoThemeTests.swift +65 -0
  88. package/dist/components/Avatar.d.ts +10 -0
  89. package/dist/components/Avatar.d.ts.map +1 -0
  90. package/dist/components/Avatar.js +16 -0
  91. package/dist/components/Badge.d.ts +10 -0
  92. package/dist/components/Badge.d.ts.map +1 -0
  93. package/dist/components/Badge.js +7 -0
  94. package/dist/components/Button.d.ts.map +1 -1
  95. package/dist/components/Button.js +1 -0
  96. package/dist/components/Icon.d.ts +10 -0
  97. package/dist/components/Icon.d.ts.map +1 -0
  98. package/dist/components/Icon.js +7 -0
  99. package/dist/components/Switch.d.ts.map +1 -1
  100. package/dist/components/Switch.js +13 -0
  101. package/dist/components/index.d.ts.map +1 -1
  102. package/dist/components/index.js +6 -0
  103. package/dist/contract/fromComponentDoc.d.ts +21 -2
  104. package/dist/contract/fromComponentDoc.d.ts.map +1 -1
  105. package/dist/contract/fromComponentDoc.js +31 -1
  106. package/dist/contract/generateSwift.d.ts.map +1 -1
  107. package/dist/contract/generateSwift.js +61 -0
  108. package/dist/contract/generateTypeScript.d.ts.map +1 -1
  109. package/dist/contract/generateTypeScript.js +13 -2
  110. package/dist/contract/parseDocType.d.ts +2 -2
  111. package/dist/contract/parseDocType.d.ts.map +1 -1
  112. package/dist/contract/parseDocType.js +7 -2
  113. package/dist/contract/types.d.ts +16 -0
  114. package/dist/contract/types.d.ts.map +1 -1
  115. package/dist/types/android.d.ts +41 -5
  116. package/dist/types/core.d.ts +27 -2
  117. package/dist/types/ios.d.ts +38 -5
  118. package/dist/types/macos.d.ts +38 -5
  119. package/dist/types/shared.d.ts +38 -5
  120. package/dist/types/windows.d.ts +41 -5
  121. package/package.json +7 -4
  122. package/src/components/Avatar.ts +27 -0
  123. package/src/components/Badge.ts +18 -0
  124. package/src/components/Button.ts +1 -0
  125. package/src/components/Icon.ts +18 -0
  126. package/src/components/Switch.ts +13 -0
  127. package/src/components/index.ts +6 -0
  128. package/src/contract/contracts.test.ts +87 -0
  129. package/src/contract/fromComponentDoc.test.ts +29 -0
  130. package/src/contract/fromComponentDoc.ts +67 -3
  131. package/src/contract/generateSwift.ts +68 -0
  132. package/src/contract/generateTypeScript.ts +13 -2
  133. package/src/contract/parseDocType.test.ts +12 -0
  134. package/src/contract/parseDocType.ts +9 -2
  135. package/src/contract/types.ts +14 -0
  136. package/src/icons/swiftIcons.test.ts +22 -0
  137. package/src/theme/swiftIOSStrings.test.ts +49 -0
  138. package/src/theme/swiftIOSTheme.test.ts +289 -0
package/README.md CHANGED
@@ -12,18 +12,22 @@ 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. iOS and macOS props sit behind `#if os(...)`. |
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
-
25
- Contracts cover Button, Card, Divider, Heading, HStack, ProgressBar, Selector,
26
- Switch, Text, TextInput, and VStack. React Native and Android bindings are not built yet; see
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
+
26
+ Contracts cover Badge, Button, Card, Divider, Heading, HStack, ProgressBar,
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
27
31
  [the experiment matrix](#experiment-matrix).
28
32
 
29
33
  ```ts
@@ -90,14 +94,17 @@ const action: AstryxAction = {
90
94
  ```
91
95
 
92
96
  ```swift
93
- let node = try JSONDecoder().decode(AstryxNode.self, from: snapshot)
94
- if case .switch(let wifi) = node {
95
- let props = wifi.viewProps { action in core.dispatch(action.json) }
97
+ let host = AstryxLogicHost(bundle: bundleSource) // calls the bundle's global astryxStart(host)
98
+ if case .switch(let wifi) = host.root {
99
+ let props = wifi.viewProps(send: host.send)
96
100
  }
97
101
  ```
98
102
 
99
103
  ```ts
104
+ // tsconfig: "customConditions": ["ios"]
105
+ import type {AstryxAction, AstryxNode} from '@astryxdesign/native/components';
100
106
  import {connectBridge, createLogicCore} from '@astryxdesign/native/logic';
107
+ import type {Bridge, BridgeHost} from '@astryxdesign/native/logic';
101
108
 
102
109
  const core = createLogicCore<{wifi: boolean}, AstryxNode, AstryxAction>({
103
110
  initial: {wifi: true},
@@ -112,20 +119,20 @@ const core = createLogicCore<{wifi: boolean}, AstryxNode, AstryxAction>({
112
119
  ? {wifi: action.args[0]}
113
120
  : state,
114
121
  });
115
- // In the app's JavaScript engine: the host reads snapshots and dispatches actions.
116
- const bridge = connectBridge(core, {
117
- connected() {},
118
- changed(json) {
119
- /* to Swift */
120
- },
121
- });
122
+ // The bundle's entry: the native host calls it with its two calls in and
123
+ // gets back the bridge it reads snapshots from and dispatches actions to.
124
+ (globalThis as {astryxStart?: (host: BridgeHost) => Bridge}).astryxStart =
125
+ host => connectBridge(core, host);
122
126
  ```
123
127
 
124
128
  ## Working on it
125
129
 
126
130
  ```sh
131
+ pnpm -F @astryxdesign/native typecheck # source and tests
127
132
  pnpm -F @astryxdesign/native build # dist/, including platform types
133
+ pnpm -F @astryxdesign/native typecheck:types # every platform's types, after build
128
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
129
136
  pnpm vitest run --project node packages/native
130
137
  ```
131
138
 
@@ -142,8 +149,23 @@ files are ignored on `main`.
142
149
  Boundaries, checked by `pnpm check:package-boundaries`:
143
150
 
144
151
  - `@astryxdesign/core` never imports this package.
145
- - This package's source never imports core. It reads core's documentation
146
- files as data at build time.
152
+ - No file in this package, in any folder, imports core, apart from the
153
+ build-time reads AST-082 FR16 lists until core's portable entry ships: the
154
+ theme generator in `scripts/` may import `@astryxdesign/core/theme` and
155
+ `@astryxdesign/core/theme/tokens`; `scripts/swift-ios-strings.mjs` may
156
+ read core's locale catalogs (`@astryxdesign/core/locales/*.json`); and
157
+ `scripts/core-docs.mjs` reads core's component documentation and built-in
158
+ icon names as data.
159
+ - The check reads source text in every folder except `node_modules`, `dist`,
160
+ `.build`, and `.swiftpm`. It flags any other module specifier that names
161
+ core (`import`, `require`, `require.resolve`, `import.meta.resolve`, or a
162
+ relative path into `packages/core`). It also flags a path to core's package,
163
+ written as adjacent string segments (`'@astryxdesign', 'core'`,
164
+ `'node_modules', '@astryxdesign/core'`, `'packages', 'core'`) or inside one
165
+ string (`node_modules/@astryxdesign/core`, `packages/core`). In
166
+ `scripts/core-docs.mjs` it allows exactly one such path, the `CORE_ROOT`
167
+ definition, and only the listed reads under `CORE_ROOT`. It does not follow
168
+ paths computed in other ways.
147
169
 
148
170
  ## Experiment matrix
149
171
 
@@ -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). The contract types under
5
- // Sources/AstryxNative/Generated are generated by `pnpm generate:apple`; do not
6
- // edit them by hand.
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: [.library(name: "AstryxNative", targets: ["AstryxNative"])],
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", "Icon/Icon.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
  )
@@ -0,0 +1,204 @@
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
+ │ │ ├── Card/ # Card
36
+ │ │ └── Banner/ # Banner
37
+ │ └── AstryxNative/ # contracts, wire, logic host (module AstryxNative)
38
+ │ └── Generated/ # generated; do not edit
39
+ ├── Tests/
40
+ │ ├── AstryxTests/
41
+ │ └── AstryxNativeTests/
42
+ └── Templates/ # page templates to copy; its own package, never published
43
+ ├── Package.swift # no products; compiles and tests the templates
44
+ ├── Login/ # LoginTemplate, from `astryx template login`
45
+ └── Tests/
46
+ ```
47
+
48
+ - **`Sources/Astryx/<Name>/`** holds one folder per component, named as in
49
+ `packages/core/src/<Name>/`. Each view has core's component name in the
50
+ `Astryx` module (`Button`, `Text`), which re-exports SwiftUI and the
51
+ generated contracts, so an app file writes `import Astryx` alone. In a file
52
+ that also imports SwiftUI, write `Astryx.Button` and `SwiftUI.Button`. A
53
+ component's parameters use core's prop names
54
+ and values (`variant: .primary`, `size: .lg`, `isLoading`), so code reads
55
+ the same across web and native. `Text`, `Heading`, and `Card` take the
56
+ generated `TextProps`, `HeadingProps`, and `CardProps`, as AST-093 FR5 asks;
57
+ the others keep four exceptions, the interim shape FR5 exempts until they move onto the generated
58
+ contracts:
59
+ - `Button` takes `action` where core has `onClick`.
60
+ - `Button` takes `fillsWidth` where core has `width="100%"`.
61
+ - `Button` takes `icon` as a shared icon name (`"search"`), which the
62
+ generated `ButtonProps` does not carry yet.
63
+ - `TextInput` takes a `Binding` where core has `value` and `onChange`.
64
+ - **`Templates/`** holds one folder per page template, named after the
65
+ `astryx template` id. Templates are clone-only, as on the web: you copy a
66
+ template's folder into your app and own it from then on. They are a
67
+ separate package with no products, so nothing imports them, and
68
+ `@astryxdesign/native` leaves them out of its npm package. A template is
69
+ built only from `Astryx` views and SwiftUI layout, and matches the web
70
+ template's content and states. Rules a template needs, such as validation,
71
+ live in a plain value type beside the view so tests can check them without a
72
+ screen.
73
+
74
+ ## Use it
75
+
76
+ Depend on the `Astryx` product. To start from a template, copy its folder,
77
+ such as `Templates/Login/`, into your app's sources; it then belongs to your
78
+ app.
79
+
80
+ ```swift
81
+ import Astryx
82
+
83
+ @main
84
+ struct DemoApp: App {
85
+ var body: some Scene {
86
+ WindowGroup {
87
+ LoginTemplate().astryxTheme() // copied from Templates/Login/
88
+ }
89
+ }
90
+ }
91
+ ```
92
+
93
+ `astryxTheme(_:)` paints a subtree with a theme; without it, components use
94
+ core's default theme. Either way they follow Dark Mode and the person's text
95
+ size.
96
+
97
+ ## Theme tokens
98
+
99
+ Components read every color, size, and font from the `astryx` environment
100
+ value, never from a constant of their own. `astryx.tokens` holds the theme's
101
+ tokens in the current mode as typed members (`tokens.color.textPrimary`,
102
+ `tokens.space.s4`, `tokens.font.body.size`), so a misspelled token fails to
103
+ compile. Font tokens come grouped: each type style (`tokens.font.body`,
104
+ `tokens.font.heading1`) holds its `size`, `weight`, and `leading`, and
105
+ `tokens.font.family`, `.size`, and `.weight` hold the scales. Text sizes grow with Dynamic Type. The components still read some
106
+ tokens by core's name (`astryx.color("color-accent")`); moving them onto the
107
+ typed members comes next.
108
+
109
+ `Icon(.search)` draws a shared icon name as the platform's SF Symbol, at
110
+ core's icon size and color, hidden from VoiceOver unless it has a `label`.
111
+ `IconName` holds every built-in name as a static member; a theme maps a name
112
+ to another symbol or to an image the app ships, or registers a
113
+ `<library>:<name>` name, with
114
+ `Theme(…, icons: ["acme:rocket": "airplane", "close": .assetName("brand.close")])`.
115
+ An asset the app does not ship stops a development build with a message that
116
+ names it, and draws nothing in a release build.
117
+
118
+ Font families come from the theme's `font-family-*` stacks: the first family
119
+ the device has wins, and a system family such as `-apple-system` or
120
+ `sans-serif` is the system font. Icons use core's shared icon names
121
+ (`success`, `warning`, …), drawn as an SF Symbol by default; a theme replaces
122
+ one with `Theme(…, icons: ["success": "checkmark.seal.fill"])`.
123
+
124
+ `Sources/Astryx/Theme/Generated/` is written by the Swift theme generator
125
+ (`../specs/swift/library/theme-generator.md`) from core's own resolver, light
126
+ and dark:
127
+
128
+ - `Tokens.swift`: the typed token surface, from core's token names.
129
+ - One `<Name>Theme.swift` per theme, declaring `Theme.<name>`: core's
130
+ defaults (`.default`) and every published theme package (`.butter`,
131
+ `.chocolate`, `.gothic`, `.matcha`, `.neutral`, `.stone`, `.y2k`).
132
+
133
+ ```swift
134
+ LoginTemplate().astryxTheme(.neutral)
135
+ ```
136
+
137
+ Regenerate after a theme or core token change:
138
+
139
+ ```sh
140
+ pnpm -F @astryxdesign/native generate:swift-ios
141
+ ```
142
+
143
+ A product generates its own theme the same way, from its theme's module and
144
+ export:
145
+
146
+ ```sh
147
+ node packages/native/scripts/swift-ios-theme.mjs --theme ./src/acmeTheme.ts#acmeTheme --out ./Sources/Theme
148
+ ```
149
+
150
+ A theme's local tokens are not generated yet; the generator names each one it
151
+ leaves out.
152
+
153
+ **Fonts.** A theme's font families are carried as data. Astryx never bundles
154
+ a font: a component walks the theme's family list in order and uses the first
155
+ family the app has registered; a system family in the list (such as
156
+ `-apple-system` or `sans-serif`) is the system font, and a list with no
157
+ registered family falls back to the system font. To draw a theme's brand face, bundle and register it
158
+ in the app. Faces the published themes name (body, heading, code):
159
+
160
+ | Theme | Faces to bundle |
161
+ | ------------ | ------------------------------------------ |
162
+ | `.default` | none (system fonts) |
163
+ | `.butter` | Outfit, JetBrains Mono |
164
+ | `.chocolate` | Albert Sans, Fraunces, JetBrains Mono |
165
+ | `.gothic` | Fustat, JetBrains Mono |
166
+ | `.matcha` | DM Sans, Playwrite US Trad, JetBrains Mono |
167
+ | `.neutral` | Figtree |
168
+ | `.stone` | Figtree, Montserrat, JetBrains Mono |
169
+ | `.y2k` | Poppins, JetBrains Mono |
170
+
171
+ The same command writes
172
+ `Sources/Astryx/Resources/<locale>.lproj/Localizable.strings` from core's
173
+ locale catalogs, so words the components speak to assistive technology, such
174
+ as a loading button's "Loading", follow the person's language. Tests in
175
+ `@astryxdesign/native` fail when either committed output drifts from core.
176
+
177
+ ## Working on it
178
+
179
+ On a Mac with Xcode or the Swift command-line tools:
180
+
181
+ ```sh
182
+ cd packages/native/apple
183
+ swift test # both products
184
+ cd Templates && swift test # templates, against the Astryx product
185
+ ```
186
+
187
+ Both packages also declare macOS 14 so they build and test on a Mac without a
188
+ simulator; iOS 17 is the target. Open `Templates/Package.swift` in Xcode to
189
+ run `LoginTemplate` in an iOS simulator through its preview.
190
+
191
+ To add a component, create `Sources/Astryx/<Name>/<Name>.swift` declaring
192
+ `<Name>` with core's prop names, writing `SwiftUI.<Name>` wherever it means the
193
+ system type, read its tokens from `astryx`, and add tests under
194
+ `Tests/AstryxTests/`. To add a template, create
195
+ `Templates/<Name>/<Name>Template.swift` from the output of
196
+ `astryx template <id>`, with tests under `Templates/Tests/`.
197
+
198
+ ## Not here yet
199
+
200
+ - The views do not use the generated contract types in `AstryxNative` yet.
201
+ Moving them onto those types is how a core prop change reaches Swift.
202
+ - Pixel and behavior parity with the web components has not been measured.
203
+ - Increase Contrast, theme-local tokens, and platform theme entries
204
+ (`defineNativeTheme`, reserved as `Theme.native`) are not wired in.
@@ -0,0 +1,210 @@
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/src/contract/contracts.test.ts,
18
+ packages/native/src/contract/parseDocType.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
+ # Avatar (Swift) component contract
29
+
30
+ ## Contract at a glance
31
+
32
+ | Area | Contract |
33
+ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
34
+ | Public contract | `Avatar(_ name: String? = nil, src:, fallbackSrc:, alt:, size: AvatarSize?, shape: AvatarShape?, tooltip: AvatarTooltip?, href:, onClick:)` and `Avatar(_ props: AvatarProps)`, a SwiftUI `View` in module `Astryx`. `size` is the named sizes `xsm` to `xl`. |
35
+ | 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. |
36
+ | 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. |
37
+ | Builder impact | An app passes a name and an image URL, and optionally tooltip words. Pixel sizes, `status`, `target`, and `rel` have no Swift form; an `href` must be an absolute URL. |
38
+ | 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. |
39
+ | 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. |
40
+ | 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/`. |
41
+
42
+ This table is a review projection; the body below is authoritative.
43
+
44
+ ## Intent
45
+
46
+ Avatar on Apple platforms shows a person's or an entity's picture with core's
47
+ fallback order, sizes, shapes, and naming, drawn with SwiftUI's own image
48
+ loading and link and button controls.
49
+
50
+ ## Compatibility and migration
51
+
52
+ - Released default preserved: `not yet released`
53
+ - Compatibility class: additive
54
+ - Controlled/uncontrolled behavior: not applicable
55
+ - Migration decision: none
56
+
57
+ Consumer migration instructions belong in consumer docs and release notes.
58
+
59
+ ## Ownership boundary
60
+
61
+ **Owns**
62
+
63
+ - Loading `src`, then `fallbackSrc`, with SwiftUI `AsyncImage`.
64
+ - Initials, the person symbol, the plate color, and the shape clip.
65
+ - Switching to a SwiftUI `Link` or `Button` for `href` or `onClick` without
66
+ changing the drawing.
67
+ - The avatar's VoiceOver name and its touch target.
68
+
69
+ **Does not own / non-goals**
70
+
71
+ - The meaning of the props, the initials rule, and the size scale — owned by
72
+ `component:Avatar`.
73
+ - Status dots and avatar groups, which have no Swift view.
74
+
75
+ ## Public concepts
76
+
77
+ | Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
78
+ | ------- | ---------------------------------------------- | --------------------------------------------------- | ----------------------------------------- | -------- | ------------------------ | ------------ | -------------------------------------------------------------------------- |
79
+ | 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 |
80
+ | shape | `circle`, `rounded`, `square` | full round, the theme's element radius, no radius | always | `circle` | `component:Avatar` | experimental | none |
81
+ | 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 |
82
+ | 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 |
83
+
84
+ ## Behavioral and layout contract
85
+
86
+ | ID | Candidate invariant | Basis | Draft review state |
87
+ | --- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------- | ------------------ |
88
+ | 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 |
89
+ | 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 |
90
+ | 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 |
91
+ | 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 |
92
+ | 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 |
93
+ | FR6 | Both initializers MUST build the same `AvatarProps`; `name` is the unlabeled first parameter and `onClick` the last, so it can be a trailing closure. 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 |
94
+ | 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 |
95
+
96
+ **Tooltip by input (FR8).** The Astryx tooltip's rules apply; this table
97
+ states Avatar's choices.
98
+
99
+ | Input | Default name | Given words | Off (`false` or blank) |
100
+ | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------ | ------------------------------------------ |
101
+ | 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 |
102
+ | 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 |
103
+ | 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 |
104
+ | 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 |
105
+
106
+ ### Allowed variation
107
+
108
+ - **AV1 — Loading.** While an image loads, the initials or the person symbol
109
+ show instead of an empty plate.
110
+ - **AV2 — Glyph.** The person symbol is the SF Symbol `person.fill`, not core's
111
+ SVG.
112
+
113
+ - **AV3 — Tooltip surface.** The tooltip is the Astryx tooltip's bubble in
114
+ core's tooltip colors on every input. SwiftUI's `.help` does not fit: it is
115
+ also the VoiceOver hint, so it would read the name twice, and it shows with
116
+ the system's look and delay, never on keyboard focus or a tap.
117
+
118
+ ### Representative states
119
+
120
+ | State | Required invariant | Allowed variation |
121
+ | ------------------------------ | -------------------------------------- | ----------------- |
122
+ | image | the image fills the shape | image content |
123
+ | failed image with a fallback | the fallback image | none |
124
+ | initials, every size and shape | initials centered on the neutral plate | glyph metrics |
125
+ | no name | the person symbol at 60% of the side | none |
126
+ | link and button | the same drawing as static | none |
127
+ | light and dark, two themes | each theme's plate and text color | none |
128
+
129
+ ### Transformation and precedence order
130
+
131
+ - **ORD1 — Picture.** `src` → `fallbackSrc` → initials → person symbol.
132
+ - **ORD2 — Name.** `alt` → `name` → none, where a blank string is none.
133
+ - **ORD3 — Control.** `href` (link) → `onClick` (button) → static.
134
+
135
+ ### Performance and resources
136
+
137
+ - **PR1 — System loading.** Images load through `AsyncImage` and the system
138
+ URL cache; the view keeps no image cache of its own.
139
+
140
+ ## Accessibility contract
141
+
142
+ - **AR1 — Named or decorative.** A static avatar with a name is one image
143
+ element named by `alt`, else `name`; without one it is hidden from VoiceOver.
144
+ A link or button avatar is one element with the link or button trait and the
145
+ same name; the initials are never an element of their own (Swift
146
+ accessibility X1, X5).
147
+ - **AR2 — Touch target.** A link or button avatar, and a static avatar whose
148
+ tap opens its tooltip, answers taps across at least 44 by 44 points without
149
+ changing its drawn size or layout (X7).
150
+ - **AR3 — Rendered tree not measured.** Tests assert what the view sets; the
151
+ rendered accessibility tree and the hit region are not measured until an
152
+ app-hosted target exists.
153
+ - **AR4 — Unnamed taps are flagged.** A link or button avatar without `alt`
154
+ or `name` logs a development warning, as core warns.
155
+ - **AR5 — Initials contrast.** The initials draw in core's tokens,
156
+ `color.textSecondary` on `color.neutral`, as core's Avatar does. In the
157
+ default and neutral themes' dark appearance that pair is below 4.5:1, in
158
+ core as well; the fix belongs to the theme tokens.
159
+
160
+ ## Design relationships
161
+
162
+ | Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
163
+ | ---------------- | ---------------------------------------- | ------------------------ | -------------- | ------------------ |
164
+ | Photo, initials | Apple Human Interface Guidelines, Images | prescribed by core | prominent | FR1–FR4 |
165
+
166
+ The component implements design requirements without copying their rationale.
167
+
168
+ Platform controls: SwiftUI `AsyncImage` for the images, SwiftUI `Link` for
169
+ `href`, and SwiftUI `Button` for `onClick` (`spec:AST-093` FR2). SwiftUI has no
170
+ avatar control, so the plate, initials, and clip are drawn here. Guideline
171
+ pages: Images, Buttons, and Accessibility in the Apple Human Interface
172
+ Guidelines.
173
+
174
+ Theme values read: `color.neutral`, `color.textSecondary`, `radius.element`,
175
+ `font.family.body`, `font.weight.medium`, and Bold Text; for the tooltip bubble,
176
+ `color.textPrimary`, `color.backgroundSurface`, `space.s1`, `space.s2`,
177
+ `radius.container`, and the body text size and weight.
178
+
179
+ ## Family and system relationships
180
+
181
+ - `component:Avatar` owns the props, the sizes, the initials rule, and the
182
+ fallback order; this record states only how Swift draws them.
183
+ - An owner that holds an Avatar in a slot leaves an unsized Avatar at `md`
184
+ (Swift slots S4).
185
+
186
+ ## Verification map
187
+
188
+ | Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
189
+ | ------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------- |
190
+ | 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` |
191
+ | 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` |
192
+ | 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` |
193
+ | 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` |
194
+ | 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` |
195
+ | AR1 | `AvatarTests.swift` naming and trait tests | `alt`, `name`, blank, none | a wrong name or a named decorative avatar fails | `audit:swift/Avatar/a11y` |
196
+ | 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` |
197
+
198
+ ## Decision log
199
+
200
+ No component-local decision is recorded.
201
+
202
+ ## Open questions
203
+
204
+ - **OQ2 — Status dots.** (`human-api`) `status` holds `AvatarStatusDot`, which
205
+ has no Swift view, so it stays on the web until one exists.
206
+
207
+ ## Content boundary
208
+
209
+ This file does not duplicate consumer prop tables/examples, current audit
210
+ results, implementation steps, or family/system rules. It links to their owners.