@astryxdesign/native 0.7.6-canary.97b3711 → 0.7.6-canary.99b8ede

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 (40) hide show
  1. package/apple/Package.swift +0 -2
  2. package/apple/README.md +19 -3
  3. package/apple/Sources/Astryx/Avatar/Avatar.swift +9 -12
  4. package/apple/Sources/Astryx/Base/SafeDestination.swift +48 -0
  5. package/apple/Sources/Astryx/Button/Button.swift +3 -21
  6. package/apple/Sources/Astryx/Item/Item.swift +446 -0
  7. package/apple/Sources/Astryx/List/ListItem.swift +255 -0
  8. package/apple/Sources/Astryx/Wire/AstryxNodeView.swift +16 -0
  9. package/apple/Sources/AstryxNative/Generated/AstryxNode.swift +6 -0
  10. package/apple/Sources/AstryxNative/Generated/Item.swift +173 -0
  11. package/apple/Sources/AstryxNative/Generated/ListItem.swift +122 -0
  12. package/apple/Tests/AstryxTests/AvatarTests.swift +14 -0
  13. package/apple/Tests/AstryxTests/ItemTests.swift +295 -0
  14. package/apple/Tests/AstryxTests/ListItemTests.swift +234 -0
  15. package/dist/components/Item.d.ts +10 -0
  16. package/dist/components/Item.d.ts.map +1 -0
  17. package/dist/components/Item.js +22 -0
  18. package/dist/components/ListItem.d.ts +10 -0
  19. package/dist/components/ListItem.d.ts.map +1 -0
  20. package/dist/components/ListItem.js +20 -0
  21. package/dist/components/index.d.ts.map +1 -1
  22. package/dist/components/index.js +4 -0
  23. package/dist/types/android.d.ts +29 -3
  24. package/dist/types/core.d.ts +30 -0
  25. package/dist/types/ios.d.ts +29 -3
  26. package/dist/types/macos.d.ts +29 -3
  27. package/dist/types/shared.d.ts +29 -3
  28. package/dist/types/windows.d.ts +29 -3
  29. package/package.json +3 -3
  30. package/src/components/Item.ts +34 -0
  31. package/src/components/ListItem.ts +32 -0
  32. package/src/components/index.ts +4 -0
  33. package/src/contract/contracts.test.ts +60 -0
  34. package/src/theme/swiftIOSTheme.test.ts +372 -38
  35. package/apple/Sources/Astryx/Avatar/Avatar.spec.md +0 -219
  36. package/apple/Sources/Astryx/Avatar/AvatarStatusDot.spec.md +0 -162
  37. package/apple/Sources/Astryx/Button/Button.spec.md +0 -174
  38. package/apple/Sources/Astryx/Icon/Icon.spec.md +0 -189
  39. package/apple/Sources/Astryx/TextInput/TextInput.spec.md +0 -179
  40. package/apple/Sources/Astryx/Thumbnail/Thumbnail.spec.md +0 -191
@@ -27,8 +27,6 @@ let package = Package(
27
27
  name: "Astryx",
28
28
  dependencies: ["AstryxNative"],
29
29
  path: "Sources/Astryx",
30
- // Each component's spec lives beside its view (AST-093 FR1).
31
- exclude: ["Avatar/Avatar.spec.md", "Avatar/AvatarStatusDot.spec.md", "Button/Button.spec.md", "Icon/Icon.spec.md", "TextInput/TextInput.spec.md", "Thumbnail/Thumbnail.spec.md"],
32
30
  resources: [.process("Resources")]
33
31
  ),
34
32
  .testTarget(name: "AstryxNativeTests", dependencies: ["AstryxNative"], path: "Tests/AstryxNativeTests"),
package/apple/README.md CHANGED
@@ -26,13 +26,15 @@ apple/
26
26
  │ │ │ └── Generated/ # typed tokens and every published theme, generated; do not edit
27
27
  │ │ ├── Resources/ # core's messages per locale, generated; do not edit
28
28
  │ │ ├── Localization/
29
- │ │ ├── Icon/ # Icon, Icon.spec.md
30
- │ │ ├── Avatar/ # Avatar, Avatar.spec.md
29
+ │ │ ├── Icon/ # Icon
30
+ │ │ ├── Avatar/ # Avatar
31
+ │ │ ├── Item/ # Item
32
+ │ │ ├── List/ # ListItem
31
33
  │ │ ├── Text/ # Text
32
34
  │ │ ├── Heading/ # Heading
33
35
  │ │ ├── Button/ # Button
34
36
  │ │ ├── TextInput/ # TextInput
35
- │ │ ├── Thumbnail/ # Thumbnail, Thumbnail.spec.md
37
+ │ │ ├── Thumbnail/ # Thumbnail
36
38
  │ │ ├── Card/ # Card
37
39
  │ │ └── Banner/ # Banner
38
40
  │ └── AstryxNative/ # contracts, wire, logic host (module AstryxNative)
@@ -46,6 +48,9 @@ apple/
46
48
  └── Tests/
47
49
  ```
48
50
 
51
+ Each component's Swift spec sits beside its core spec, at
52
+ `docs/specs/components/<ComponentRoot>/<Name>.swift.spec.md`.
53
+
49
54
  - **`Sources/Astryx/<Name>/`** holds one folder per component, named as in
50
55
  `packages/core/src/<Name>/`. Each view has core's component name in the
51
56
  `Astryx` module (`Button`, `Text`), which re-exports SwiftUI and the
@@ -143,6 +148,17 @@ export:
143
148
  node packages/native/scripts/swift-ios-theme.mjs --theme ./src/acmeTheme.ts#acmeTheme --out ./Sources/Theme
144
149
  ```
145
150
 
151
+ The generator reads the CSS forms its spec lists
152
+ (`specs/swift/library/theme-generator.md`, G7): hex and named colors, `rgb()`,
153
+ `hsl()`, `hwb()`, Lab, LCH, OKLab, OKLCH, `color()` in the listed spaces,
154
+ `color-mix()`, and relative colors (wide-gamut colors kept as Display P3),
155
+ lengths with `calc()`, and `[light, dark]` tuples. A value it can only
156
+ approximate, such as a color outside Display P3 (clipped, as browsers draw it),
157
+ prints a warning after the run; a value with no static form, such as
158
+ `currentColor` or `50%`, takes core's default for that token with a warning, or
159
+ stops the run when core has none. A form the generator does not read yet stops
160
+ the run, saying so. Add `--strict` to fail on any warning.
161
+
146
162
  A theme's local tokens are not generated yet; the generator names each one it
147
163
  leaves out.
148
164
 
@@ -77,10 +77,7 @@ public struct Avatar<Status: View>: View {
77
77
  /// the build with its value, and an unnamed link or button is flagged.
78
78
  private func checkInDevelopment() {
79
79
  #if DEBUG
80
- if Avatar.isUnusableHref(props.href) {
81
- assertionFailure(
82
- "Avatar href \"\(props.href ?? "")\" is not an absolute URL an app can open; it draws without a link.")
83
- }
80
+ astryxCheckHref(props.href, in: "Avatar")
84
81
  // The avatar's own name: a status label alone does not name a person.
85
82
  let ownName = Avatar.meaningful(props.alt) ?? Avatar.meaningful(props.name)
86
83
  if Avatar.needsNameWarning(tap: tap, isNamed: ownName != nil) {
@@ -108,11 +105,7 @@ public struct Avatar<Status: View>: View {
108
105
  }
109
106
 
110
107
  /// A non-empty `href` that is not an absolute URL, such as a web path.
111
- nonisolated static func isUnusableHref(_ href: String?) -> Bool {
112
- guard let href, !href.isEmpty else { return false }
113
- guard let url = URL(string: href) else { return true }
114
- return url.scheme == nil
115
- }
108
+ nonisolated static func isUnusableHref(_ href: String?) -> Bool { astryxIsUnusableHref(href) }
116
109
 
117
110
  /// The picture as a link with `href`, a button with only `onClick`, or a
118
111
  /// static image (Swift component API, A4). All three draw the same.
@@ -309,9 +302,13 @@ public struct Avatar<Status: View>: View {
309
302
 
310
303
  /// The URL the avatar opens, or `nil` when it has no usable `href`.
311
304
  var linkURL: URL? {
312
- // Only an absolute URL the system can open; a malformed or relative
313
- // `href` leaves the avatar static or a button.
314
- guard let url = url(props.href), url.scheme != nil else { return nil }
305
+ // Only an absolute URL the system can open, and never one core's
306
+ // navigation destinations refuse (a script URL or an HTML `data:` URL);
307
+ // a malformed, relative, or refused `href` leaves the avatar static or a
308
+ // button.
309
+ guard let href = props.href, astryxSafeDestination(href) != nil,
310
+ let url = url(href), url.scheme != nil
311
+ else { return nil }
315
312
  return url
316
313
  }
317
314
 
@@ -0,0 +1,48 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ import Foundation
4
+
5
+ /// An `href` as a link reads it: control characters removed and surrounding
6
+ /// whitespace trimmed, as core's shared destination rule does.
7
+ func astryxNormalizedHref(_ href: String) -> String {
8
+ String(String.UnicodeScalarView(
9
+ href.unicodeScalars.filter { $0.value > 0x1F && $0.value != 0x7F }
10
+ )).trimmingCharacters(in: .whitespacesAndNewlines)
11
+ }
12
+
13
+ /// A destination a link may open, normalized as core's shared rule does, or
14
+ /// nil for a script URL or an HTML document in a `data:` URL, which core's
15
+ /// navigation destinations refuse (`family:navigation-destinations` FR4).
16
+ /// The scheme is compared in lowercase without the spaces after its colon,
17
+ /// which a data URL's media type ignores (`data: text/html` is HTML).
18
+ func astryxSafeDestination(_ href: String) -> String? {
19
+ let normalized = astryxNormalizedHref(href)
20
+ var comparable = normalized.lowercased()
21
+ if let colon = comparable.firstIndex(of: ":"),
22
+ comparable[..<colon].range(of: "^[a-z][a-z0-9+.-]*$", options: .regularExpression) != nil {
23
+ let rest = comparable[comparable.index(after: colon)...].drop { $0 == " " }
24
+ comparable = String(comparable[...colon]) + rest
25
+ }
26
+ for blocked in ["javascript:", "vbscript:", "data:text/html"] where comparable.hasPrefix(blocked) {
27
+ return nil
28
+ }
29
+ return normalized
30
+ }
31
+
32
+ /// A non-empty `href` that is not an absolute URL, such as a web path. Pass
33
+ /// the `href` as the view's link reads it, so the check and the link agree.
34
+ func astryxIsUnusableHref(_ href: String?) -> Bool {
35
+ guard let href, !href.isEmpty else { return false }
36
+ guard let url = URL(string: href) else { return true }
37
+ return url.scheme == nil
38
+ }
39
+
40
+ /// Stops a development build on an `href` an app cannot open, naming the
41
+ /// component and the value; a release build draws the view without a link.
42
+ func astryxCheckHref(_ href: String?, in component: String) {
43
+ #if DEBUG
44
+ if astryxIsUnusableHref(href) {
45
+ assertionFailure("\(component) href \"\(href ?? "")\" is not an absolute URL an app can open; it draws without a link.")
46
+ }
47
+ #endif
48
+ }
@@ -82,27 +82,9 @@ public struct Button: View {
82
82
  /// disabled button, as core draws a disabled `<button>`.
83
83
  var link: URL? { isDisabled ? nil : destination }
84
84
 
85
- /// A destination a link may open, normalized as core's shared rule does, or
86
- /// nil for a script URL or an HTML document in a `data:` URL, which core's
87
- /// navigation destinations refuse (`family:navigation-destinations` FR4).
88
- /// Control characters are removed and whitespace trimmed; the scheme is
89
- /// compared in lowercase without the spaces after its colon, which a data
90
- /// URL's media type ignores (`data: text/html` is HTML).
91
- nonisolated static func safeDestination(_ href: String) -> String? {
92
- let normalized = String(String.UnicodeScalarView(
93
- href.unicodeScalars.filter { $0.value > 0x1F && $0.value != 0x7F }
94
- )).trimmingCharacters(in: .whitespacesAndNewlines)
95
- var comparable = normalized.lowercased()
96
- if let colon = comparable.firstIndex(of: ":"),
97
- comparable[..<colon].range(of: "^[a-z][a-z0-9+.-]*$", options: .regularExpression) != nil {
98
- let rest = comparable[comparable.index(after: colon)...].drop { $0 == " " }
99
- comparable = String(comparable[...colon]) + rest
100
- }
101
- for blocked in ["javascript:", "vbscript:", "data:text/html"] where comparable.hasPrefix(blocked) {
102
- return nil
103
- }
104
- return normalized
105
- }
85
+ /// A destination a link may open, or nil when core's navigation
86
+ /// destinations refuse it (`astryxSafeDestination`).
87
+ nonisolated static func safeDestination(_ href: String) -> String? { astryxSafeDestination(href) }
106
88
 
107
89
  public var body: some View {
108
90
  control
@@ -0,0 +1,446 @@
1
+ // Copyright (c) Meta Platforms, Inc. and affiliates.
2
+
3
+ import AstryxNative
4
+ import SwiftUI
5
+
6
+ #if canImport(UIKit)
7
+ import UIKit
8
+ #elseif canImport(AppKit)
9
+ import AppKit
10
+ #endif
11
+
12
+ /// A row: optional marker and leading content, a label with an optional
13
+ /// description, and optional trailing content (core `Item`). With `onClick`
14
+ /// it is a button and with `href` a link; either way it draws the same row.
15
+ ///
16
+ /// ```swift
17
+ /// Item("Ada Lovelace", description: "Mathematician") {
18
+ /// Icon(.check)
19
+ /// } endContent: {
20
+ /// Icon(.chevronRight, color: .secondary)
21
+ /// }
22
+ /// Item("Notifications", onClick: openNotifications)
23
+ /// Item("Archive") { Icon(.upload) } onClick: { archive() }
24
+ /// ```
25
+ public struct Item<Marker: View, StartContent: View, EndContent: View>: View {
26
+ /// The contract the view draws, the same for every initializer.
27
+ public let props: ItemProps
28
+ let marker: Marker
29
+ let startContent: StartContent
30
+ let endContent: EndContent
31
+ @Environment(\.astryx) private var astryx
32
+ @Environment(\.astryxItemListTreatment) private var listTreatment
33
+ @State private var wordsHeight: CGFloat = 0
34
+
35
+ /// A row from its labeled props. A single trailing closure is the start
36
+ /// content; set `onClick` by label or as a trailing `onClick:` closure.
37
+ /// - Parameters:
38
+ /// - label: The row's main words (core `label`).
39
+ /// - description: Supporting words under or beside the label (core `description`).
40
+ /// - align: How the start and end content line up with the words: `center`, `start`, or `firstLine`; `nil` is `center` (core `align`).
41
+ /// - density: `compact`, `balanced`, or `spacious` padding; `nil` is `balanced` (core `density`).
42
+ /// - labelLines: Lines the label may take before it truncates; `nil` is one (core `labelLines`).
43
+ /// - descriptionLines: Lines the description may take before it truncates; `nil` is one (core `descriptionLines`).
44
+ /// - layout: `stacked` puts the description under the label, `inline` beside it; `nil` is `stacked` (core `layout`).
45
+ /// - href: A URL the system opens when the row is tapped; the row becomes a link and `onClick` does not run (core `href`).
46
+ /// - isHighlighted: Draws the row's highlighted background (core `isHighlighted`).
47
+ /// - isSelected: Draws the row as selected and reads it as selected (core `isSelected`).
48
+ /// - isDisabled: Dims the row; a button or link row stays reachable and does nothing (core `isDisabled`).
49
+ /// - startContent: Content before the words: an `Icon`, an `Avatar`, or a checkbox (core `startContent`).
50
+ /// - endContent: Content after the words, such as a badge, a value, or an icon (core `endContent`).
51
+ /// - marker: A list marker before the start content; pass every slot by label when you set it (core `marker`).
52
+ /// - onClick: Runs when the row is tapped; the row becomes a button when it has no `href` (core `onClick`).
53
+ public init(
54
+ _ label: String,
55
+ description: String? = nil,
56
+ align: ItemAlign? = nil,
57
+ density: ItemDensity? = nil,
58
+ labelLines: Double? = nil,
59
+ descriptionLines: Double? = nil,
60
+ layout: ItemLayout? = nil,
61
+ href: String? = nil,
62
+ isHighlighted: Bool? = nil,
63
+ isSelected: Bool? = nil,
64
+ isDisabled: Bool? = nil,
65
+ @ViewBuilder startContent: () -> StartContent = { EmptyView() },
66
+ @ViewBuilder endContent: () -> EndContent = { EmptyView() },
67
+ @ViewBuilder marker: () -> Marker = { EmptyView() },
68
+ onClick: (() -> Void)? = nil
69
+ ) {
70
+ self.init(
71
+ ItemProps(
72
+ label: label, description: description, align: align, density: density, labelLines: labelLines,
73
+ descriptionLines: descriptionLines, layout: layout, onClick: onClick, href: href,
74
+ isHighlighted: isHighlighted, isSelected: isSelected, isDisabled: isDisabled
75
+ ),
76
+ startContent: startContent, endContent: endContent, marker: marker
77
+ )
78
+ }
79
+
80
+ /// A row from its generated contract, for generated and wire-driven callers.
81
+ public init(
82
+ _ props: ItemProps,
83
+ @ViewBuilder startContent: () -> StartContent = { EmptyView() },
84
+ @ViewBuilder endContent: () -> EndContent = { EmptyView() },
85
+ @ViewBuilder marker: () -> Marker = { EmptyView() }
86
+ ) {
87
+ self.props = props
88
+ self.marker = marker()
89
+ self.startContent = startContent()
90
+ self.endContent = endContent()
91
+ }
92
+
93
+ public var body: some View {
94
+ control
95
+ .onAppear(perform: checkInDevelopment)
96
+ .astryxBase(props.base)
97
+ }
98
+
99
+ /// An `href` an app cannot open, such as a web path, stops a development
100
+ /// build with its value; a release build draws the row without a link.
101
+ private func checkInDevelopment() {
102
+ astryxCheckHref(props.href.map(astryxNormalizedHref), in: "Item")
103
+ }
104
+
105
+ /// A non-empty `href` that is not an absolute URL, read as the row's link
106
+ /// reads it (trimmed, control characters removed).
107
+ nonisolated static func isUnusableHref(_ href: String?) -> Bool {
108
+ astryxIsUnusableHref(href.map(astryxNormalizedHref))
109
+ }
110
+
111
+ /// The row as a link with `href`, a button with only `onClick`, or static
112
+ /// (Swift component API, A4). All three draw the same row.
113
+ @ViewBuilder private var control: some View {
114
+ if let url = linkURL {
115
+ SwiftUI.Link(destination: url) { row(minHeight: Item.minimumTarget, paintsFill: false) }
116
+ .buttonStyle(pressStyle)
117
+ .disabled(isDisabled)
118
+ .modifier(ItemAccessibility(isSelected: isSelected))
119
+ } else if let onClick = props.onClick {
120
+ SwiftUI.Button(action: onClick) { row(minHeight: Item.minimumTarget, paintsFill: false) }
121
+ .buttonStyle(pressStyle)
122
+ .disabled(isDisabled)
123
+ .modifier(ItemAccessibility(isSelected: isSelected))
124
+ } else {
125
+ row(minHeight: nil, paintsFill: true)
126
+ .accessibilityElement(children: .combine)
127
+ // A disabled row reads as dimmed, as core marks it aria-disabled.
128
+ .disabled(isDisabled)
129
+ .modifier(ItemAccessibility(isSelected: isSelected))
130
+ }
131
+ }
132
+
133
+ /// A link or button row's fill and its press, painted by the button style
134
+ /// so the press sits above a selected or highlighted fill, as core's does.
135
+ private var pressStyle: ItemPressStyle {
136
+ ItemPressStyle(radius: cornerRadius, fill: background, pressed: astryx.tokens.color.overlayPressed)
137
+ }
138
+
139
+ /// The row's drawing; a tappable row is at least `minHeight` tall. A static
140
+ /// row paints its own fill; a link or button row's style paints it.
141
+ private func row(minHeight: CGFloat?, paintsFill: Bool) -> some View {
142
+ HStack(alignment: rowAlignment, spacing: astryx.tokens.space.s2) {
143
+ markerSlot
144
+ // A list's treatment is for this row only, not for rows nested in its slots.
145
+ slot(startContent.modifier(ItemSlotOutsideList()))
146
+ // A disabled row dims its words and end content, as core does; the
147
+ // marker and start content keep their own look (a checkbox shows its
148
+ // own disabled state).
149
+ words
150
+ .frame(maxWidth: .infinity, alignment: .leading)
151
+ .modifier(ItemWordsHeight(isMeasured: measuresWords, height: $wordsHeight))
152
+ .opacity(isDisabled ? 0.5 : 1)
153
+ slot(endContent.modifier(ItemSlotOutsideList()))
154
+ .opacity(isDisabled ? 0.5 : 1)
155
+ }
156
+ .padding(.horizontal, inlinePadding)
157
+ .padding(.vertical, blockPadding)
158
+ .frame(maxWidth: .infinity, minHeight: minHeight, alignment: .leading)
159
+ .background(
160
+ RoundedRectangle(cornerRadius: cornerRadius, style: .continuous)
161
+ .fill(paintsFill ? background ?? .clear : .clear)
162
+ )
163
+ .contentShape(Rectangle())
164
+ }
165
+
166
+ /// A slot's content. For `firstLine`, its center sits on the center of
167
+ /// the label's first line box, however tall the slot is.
168
+ @ViewBuilder private func slot<Content: View>(_ content: Content) -> some View {
169
+ if resolvedAlign == .firstLine {
170
+ let lineCenterAboveBaseline = firstLineCenterAboveBaseline
171
+ content.alignmentGuide(.firstTextBaseline) { d in d.height / 2 + lineCenterAboveBaseline }
172
+ } else {
173
+ content
174
+ }
175
+ }
176
+
177
+ /// The marker. Inside a list it centers on the label's first line,
178
+ /// whatever the row's alignment, as core's list markers do.
179
+ @ViewBuilder private var markerSlot: some View {
180
+ if listTreatment?.markerOnFirstLine == true {
181
+ let center = firstLineBoxHeight / 2
182
+ switch resolvedAlign {
183
+ case .firstLine:
184
+ slot(marker)
185
+ case .start:
186
+ marker.alignmentGuide(.top) { d in d.height / 2 - center }
187
+ case .center:
188
+ let words = wordsHeight
189
+ marker.alignmentGuide(VerticalAlignment.center) { d in words / 2 - center + d.height / 2 }
190
+ }
191
+ } else {
192
+ slot(marker)
193
+ }
194
+ }
195
+
196
+ /// Whether the row measures its words: only a centre-aligned row in a list
197
+ /// with markers, which places its marker from the words' height.
198
+ private var measuresWords: Bool {
199
+ listTreatment?.markerOnFirstLine == true && resolvedAlign == .center
200
+ }
201
+
202
+ /// The height of the label's first line box: the theme's leading at the
203
+ /// current text size.
204
+ private var firstLineBoxHeight: CGFloat {
205
+ astryx.tokens.font.body.leading * astryx.tokens.font.body.size * astryx.textScale
206
+ }
207
+
208
+ /// The row's corner radius: the theme's element radius, or square inside a
209
+ /// list with dividers.
210
+ private var cornerRadius: CGFloat {
211
+ listTreatment?.squareCorners == true ? 0 : astryx.tokens.radius.element
212
+ }
213
+
214
+ @ViewBuilder private var words: some View {
215
+ let label = SwiftUI.Text(props.label)
216
+ .font(astryx.font(size: "text-body-size", 14, weight: "text-body-weight"))
217
+ .foregroundStyle(astryx.tokens.color.textPrimary)
218
+ .lineLimit(Item.lines(props.labelLines))
219
+ .modifier(ItemLeading(extra: extraLeading(astryx.tokens.font.body.leading, size: astryx.tokens.font.body.size)))
220
+ let description = props.description.map { words in
221
+ SwiftUI.Text(words)
222
+ .font(astryx.font(size: "text-supporting-size", 12, weight: "text-supporting-weight"))
223
+ .foregroundStyle(astryx.tokens.color.textSecondary)
224
+ .lineLimit(Item.lines(props.descriptionLines))
225
+ .modifier(
226
+ ItemLeading(extra: extraLeading(astryx.tokens.font.supporting.leading, size: astryx.tokens.font.supporting.size)))
227
+ }
228
+ // Inline only with a description, as core's: a label alone keeps its
229
+ // width limit and truncates.
230
+ if (props.layout ?? .stacked) == .inline, description != nil {
231
+ HStack(alignment: .firstTextBaseline, spacing: astryx.tokens.space.s1) {
232
+ label.fixedSize(horizontal: true, vertical: false)
233
+ description
234
+ }
235
+ } else {
236
+ VStack(alignment: .leading, spacing: 0) {
237
+ label
238
+ description
239
+ }
240
+ }
241
+ }
242
+
243
+ var resolvedAlign: ItemAlign { props.align ?? .center }
244
+
245
+ private var rowAlignment: VerticalAlignment {
246
+ switch resolvedAlign {
247
+ case .center: .center
248
+ case .start: .top
249
+ case .firstLine: .firstTextBaseline
250
+ }
251
+ }
252
+
253
+ /// How far the center of the label's first line sits above its baseline:
254
+ /// half the font's line height above the line's bottom, less the descent,
255
+ /// in the font's own metrics at the current text size. The theme's extra
256
+ /// leading is split evenly above and below, so it does not move the center.
257
+ var firstLineCenterAboveBaseline: CGFloat {
258
+ let metrics = astryxSystemFontMetrics(astryx.tokens.font.body.size)
259
+ return (metrics.ascender - metrics.lineHeight / 2) * astryx.textScale
260
+ }
261
+
262
+ var isDisabled: Bool { props.isDisabled == true }
263
+ var isSelected: Bool { props.isSelected == true }
264
+
265
+ /// Selected wins over highlighted, as core's styles order them.
266
+ var background: Color? {
267
+ if isSelected { return astryx.tokens.color.accentMuted }
268
+ if props.isHighlighted == true { return astryx.tokens.color.overlayHover }
269
+ return nil
270
+ }
271
+
272
+ /// Block padding per density: spacing 1, 2, or 3.
273
+ var blockPadding: CGFloat {
274
+ switch props.density ?? .balanced {
275
+ case .compact: astryx.tokens.space.s1
276
+ case .balanced: astryx.tokens.space.s2
277
+ case .spacious: astryx.tokens.space.s3
278
+ }
279
+ }
280
+
281
+ /// Inline padding: the list's own inset when a list sets one, else core's
282
+ /// for the density.
283
+ var inlinePadding: CGFloat {
284
+ listTreatment?.inlineInset ?? Item.inlinePadding(density: props.density, tokens: astryx.tokens)
285
+ }
286
+
287
+ /// Core's inline padding for a density: spacing 2, or 3 when spacious.
288
+ static func inlinePadding(density: ItemDensity?, tokens: Tokens) -> CGFloat {
289
+ (density ?? .balanced) == .spacious ? tokens.space.s3 : tokens.space.s2
290
+ }
291
+
292
+ /// The space core's line height adds to the font's own line, grown with
293
+ /// Dynamic Type, so a line takes the theme's leading as on the web. The
294
+ /// leading tokens are unitless line heights, as in CSS.
295
+ private func extraLeading(_ leading: CGFloat, size: CGFloat) -> CGFloat {
296
+ max(0, leading * size - astryxSystemLineHeight(size)) * astryx.textScale
297
+ }
298
+
299
+ /// The URL the row opens, or `nil` when it has no usable `href`.
300
+ var linkURL: URL? {
301
+ // Only an absolute URL the system can open, and never one core's
302
+ // navigation destinations refuse (a script URL or an HTML `data:` URL);
303
+ // a malformed, relative, or refused `href` leaves the row static or a
304
+ // button.
305
+ guard let href = props.href, let safe = astryxSafeDestination(href), !safe.isEmpty,
306
+ let url = URL(string: safe), url.scheme != nil
307
+ else { return nil }
308
+ return url
309
+ }
310
+
311
+ /// How the row takes a tap: a link with a usable `href`, else a button
312
+ /// with `onClick`, else none.
313
+ enum Tap: Equatable { case link, button, none }
314
+
315
+ var tap: Tap {
316
+ if linkURL != nil { return .link }
317
+ if props.onClick != nil { return .button }
318
+ return .none
319
+ }
320
+
321
+ /// The traits the row adds to what its control already carries: selected
322
+ /// when selected. A link or button keeps its own trait (X1).
323
+ nonisolated static func addedTraits(isSelected: Bool) -> AccessibilityTraits {
324
+ isSelected ? .isSelected : []
325
+ }
326
+
327
+ /// A tappable row is at least 44 points tall (Swift accessibility, X7).
328
+ static var minimumTarget: CGFloat { 44 }
329
+
330
+ /// The line limit for `labelLines` or `descriptionLines`: one when unset,
331
+ /// as core's row truncates a label to one line by default, and otherwise
332
+ /// core's shared count (`astryxLineLimit`), so zero shows every line.
333
+ nonisolated static func lines(_ value: Double?) -> Int? { astryxLineLimit(value ?? 1) }
334
+ }
335
+
336
+ /// Paints a link or button row's fill and, while pressed, the pressed
337
+ /// overlay above it, as core's interactive rows do.
338
+ struct ItemPressStyle: ButtonStyle {
339
+ let radius: CGFloat
340
+ /// The selected or highlighted fill, if any.
341
+ let fill: Color?
342
+ let pressed: Color
343
+
344
+ func makeBody(configuration: Configuration) -> some View {
345
+ configuration.label
346
+ .background(ItemPressBackground(radius: radius, fill: fill, pressed: pressed, isPressed: configuration.isPressed))
347
+ }
348
+ }
349
+
350
+ /// The fill with the press above it.
351
+ struct ItemPressBackground: View {
352
+ let radius: CGFloat
353
+ let fill: Color?
354
+ let pressed: Color
355
+ let isPressed: Bool
356
+
357
+ var body: some View {
358
+ let shape = RoundedRectangle(cornerRadius: radius, style: .continuous)
359
+ ZStack {
360
+ shape.fill(fill ?? .clear)
361
+ shape.fill(isPressed ? pressed : .clear)
362
+ }
363
+ }
364
+ }
365
+
366
+ /// Spreads the extra leading between lines and half above and below, as a
367
+ /// CSS line height does.
368
+ private struct ItemLeading: ViewModifier {
369
+ let extra: CGFloat
370
+
371
+ func body(content: Content) -> some View {
372
+ content.lineSpacing(extra).padding(.vertical, extra / 2)
373
+ }
374
+ }
375
+
376
+ /// The system font's own line height at a size.
377
+ func astryxSystemLineHeight(_ size: CGFloat) -> CGFloat {
378
+ astryxSystemFontMetrics(size).lineHeight
379
+ }
380
+
381
+ /// The system font's ascender and line height at a size.
382
+ func astryxSystemFontMetrics(_ size: CGFloat) -> (ascender: CGFloat, lineHeight: CGFloat) {
383
+ #if canImport(UIKit)
384
+ let font = UIFont.systemFont(ofSize: size)
385
+ return (font.ascender, font.lineHeight)
386
+ #elseif canImport(AppKit)
387
+ let font = NSFont.systemFont(ofSize: size)
388
+ return (font.ascender, font.ascender - font.descender + font.leading)
389
+ #else
390
+ return (size * 0.95, size * 1.2)
391
+ #endif
392
+ }
393
+
394
+ /// A selected row reads as selected (Swift accessibility, X1).
395
+ private struct ItemAccessibility: ViewModifier {
396
+ let isSelected: Bool
397
+
398
+ func body(content: Content) -> some View {
399
+ content.accessibilityAddTraits(Item<EmptyView, EmptyView, EmptyView>.addedTraits(isSelected: isSelected))
400
+ }
401
+ }
402
+
403
+ /// Measures the words' height only when the row needs it.
404
+ private struct ItemWordsHeight: ViewModifier {
405
+ let isMeasured: Bool
406
+ @Binding var height: CGFloat
407
+
408
+ func body(content: Content) -> some View {
409
+ if isMeasured {
410
+ content.onGeometryChange(for: CGFloat.self) { $0.size.height } action: { height = $0 }
411
+ } else {
412
+ content
413
+ }
414
+ }
415
+ }
416
+
417
+ /// A row's slots sit outside its list: a row nested in a slot takes neither
418
+ /// the list's treatment, its look, nor a number from it.
419
+ private struct ItemSlotOutsideList: ViewModifier {
420
+ func body(content: Content) -> some View {
421
+ content
422
+ .environment(\.astryxItemListTreatment, nil)
423
+ .environment(\.astryxListContext, nil)
424
+ .environment(\.astryxListNumbers, nil)
425
+ }
426
+ }
427
+
428
+ /// How a list draws the rows it holds: the marker on the first line, its own
429
+ /// inline inset (zero for a flush list), and square corners between dividers.
430
+ struct ItemListTreatment: Equatable {
431
+ var markerOnFirstLine: Bool
432
+ var inlineInset: CGFloat?
433
+ var squareCorners: Bool
434
+ }
435
+
436
+ private struct ItemListTreatmentKey: EnvironmentKey {
437
+ static let defaultValue: ItemListTreatment? = nil
438
+ }
439
+
440
+ extension EnvironmentValues {
441
+ /// Set by `ListItem` on the `Item` it draws; `nil` for an `Item` alone.
442
+ var astryxItemListTreatment: ItemListTreatment? {
443
+ get { self[ItemListTreatmentKey.self] }
444
+ set { self[ItemListTreatmentKey.self] = newValue }
445
+ }
446
+ }