An open source design system that's fully customizable and agent ready
TypeScript
spec(native): typed slots for Swift (text, icon, named components, content) (#8037)
Cindy Zhang15ee09176e1d
diff --git a/packages/native/specs/swift/library/README.md b/packages/native/specs/swift/library/README.mdindex 461f432c46..5f5b39f484 100644--- a/packages/native/specs/swift/library/README.md+++ b/packages/native/specs/swift/library/README.md@@ -11,4 +11,5 @@ wins.| File | Concern || -------------------- | ------------------------------------------------------------------------------------- || `accessibility.md` | How core's accessibility semantics reach VoiceOver and Apple's accessibility settings |+| `slots.md` | How each slot kind (text, icon, content) appears in SwiftUI || `theme-generator.md` | How any Astryx theme becomes a Swift `AstryxTheme` |diff --git a/packages/native/specs/swift/library/slots.md b/packages/native/specs/swift/library/slots.mdnew file mode 100644index 0000000000..dfc59cff2a--- /dev/null+++ b/packages/native/specs/swift/library/slots.md@@ -0,0 +1,96 @@+# Typed slots (Swift)++- Status: draft+- Relation: applies AST-082 FR4+ (`docs/specs/AST-082-native-first-surfaces/spec.md`: typed slots, text,+ icon, and content, and a platform's wider form for a content slot with the+ same meaning), and FR17 (shared icon names) to Swift. It decides how each slot kind appears in+ SwiftUI; it does not define the kinds.++## Summary++An iOS developer can put an icon in a button, an avatar at the start of a list+row, or any SwiftUI view at its end, the way SwiftUI's own `Label` takes an+icon view, and the component still sizes and orders what it holds, so every+row lines up and reads the same way. Icons are always ones the platform can+draw. The person using the app sees the same parts in the same+places as on the web, read by VoiceOver in the same order.++## Requirements++- **S1 — Each AST-082 slot kind has one Swift form.**+ - A **text** slot is a `String`, the contract's exact type (AST-093 FR5). A+ localized text spelling is outside this record.+ - An **icon** slot is an `IconName` (S2).+ - A **content** slot accepts any SwiftUI view, through a `@ViewBuilder`+ closure (S3). The core's content slot holds named Astryx components; Swift+ accepts this wider form under AST-082 FR4, which lets a platform accept a+ wider form for a content slot with the same meaning, as the web+ accepts a React node. The component's native additions still name the Astryx+ components the core slot holds, and whether it holds one or many (a list item's `startContent` holds one of `Icon`, `Avatar`, or `CheckboxInput`; a card holds many).+ Text and icon slots take no wider form (no attributed text, no image), so+ they mean the same thing on Swift as in the core; a localized text+ spelling stays outside this record, as above. A free-form web+ prop with no slot kind stays in the web contract only.+- **S2 — Icon names are a string-backed type with the built-ins as members.**+ `IconName` is a `RawRepresentable`, `ExpressibleByStringLiteral`,+ `Hashable`, `Codable`, `Sendable` value. Every built-in semantic name is a+ static member (`.search`, `.close`), generated from AST-082 FR17's shared+ icon names, read at build time through the icon-names read AST-082 FR16 lists+ (later through core's portable entry), never from core's web icon registry. A+ namespaced name (`"acme:rocket"`) is valid once the app registers it in code+ with the image to draw (an SF Symbol name or an asset). An unknown name+ stops a development build with a message naming it, and draws nothing in a+ release build, never a substitute.+- **S3 — Content slots are open, the SwiftUI way.** A content slot is a generic+ `@ViewBuilder` closure parameter named as the core prop+ (`startContent: () -> StartContent` where `StartContent: View`), as in+ SwiftUI's `Label { } icon: { }`, never `AnyView`. For+ each Astryx component the core slot names, the view also has a convenience+ initializer that takes that component's props directly (for example a row's+ `startContent: AvatarProps`). The props initializer takes the slot as the matching+ generated node type.+- **S4 — The owner sizes what it holds.** A component proposes the size of+ each slot from its own size and clips or aligns what the slot draws to it,+ whatever view is in it. An Astryx child inherits its owner's size only where+ core's does: an `Icon` in an owner's documented icon slot (an `Icon` in a+ small `IconButton` is small), and a child of a component whose contract+ adopts the size cascade. Every other child keeps its own default (an unsized `Avatar` in a list item+ stays `md`). An explicit size on a child wins wherever core's does, and a+ component that sizes its members in core keeps doing so: core's `AvatarGroup`+ sets every member `Avatar`'s size, explicit or not.+- **S5 — Reading order follows the slots.** VoiceOver reads a component's slots+ in the core contract's order (for a list item: `marker`, `startContent`,+ `label`, `description`, `endContent`), whatever views they hold. A decorative+ icon in a slot is hidden unless it carries a label (AST-082 FR17).+- **S6 — Slots are declared, not guessed.** Each component's native additions+ name the slot kind, and for a content slot the Astryx components the core+ slot holds, for every free-form prop it keeps; the contract generator fails+ when a kept free-form prop has none.++## Acceptance checks++| Requirement | Check |+| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |+| S1, S6 | The generator test fails on a fixture component that keeps a free-form prop with no slot kind, or keeps a content slot that names no components; a fixture's unkept free-form prop stays web-only with no Swift form; a fixture with all three kinds produces each Swift form. |+| S2 | Every built-in name maps to an SF Symbol that exists on the package's iOS floor; registering `acme:rocket` makes `"acme:rocket"` draw it; an unregistered name stops a development build and draws nothing in release. |+| S3 | A compile test passes `Avatar(…)` into a list item's `startContent` through the closure, through the `AvatarProps` convenience initializer, and a plain SwiftUI `Image` through the closure; `AnyView` does not appear in the components module. |+| S4 | A test reads the resolved size of an unsized icon in a small and a large owner's icon slot, finds an unsized `Avatar` in a list item at `md`, and finds the drawn bounds of an oversized SwiftUI view in `startContent` within the slot. |+| S5 | A UI test reads a list item with a marker, `startContent`, label, description, and `endContent` in that order, with an Astryx badge and with a plain SwiftUI text in `endContent`. |++## Current state++- The contract generator knows two slot kinds, `text` and `content`; an icon+ prop has no portable form, so the icon props of Button and Badge are+ web-only.+- The built-in icon names map to SF Symbols in TypeScript only.++## Open questions++None.++## References++- HIG, SF Symbols: https://developer.apple.com/design/human-interface-guidelines/sf-symbols+- `ViewBuilder`: https://developer.apple.com/documentation/swiftui/viewbuilder+- SwiftUI `Label` (open icon slot): https://developer.apple.com/documentation/swiftui/label