@astryxdesign/native 0.7.5-canary.f2dafed → 0.7.5-canary.f57df18

package/README.md

@@ -12,16 +12,23 @@ rests on evidence.
 
 ## What is here today
 
-| Part           | Path                              | What it does                                                                                                                                                                                                                                 |
-| -------------- | --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 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. |
-| 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.                                                                                            |
-| Swift binding  | `apple/`                          | A Swift package with props generated from the same contracts. iOS and macOS props sit behind `#if os(...)`.                                                                                                                                  |
-| 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.                                                                                |
-| Icons          | `NATIVE_ICON_DEFAULTS`            | Astryx's built-in icon names mapped to SF Symbols on Apple platforms and Material Symbols on Android.                                                                                                                                        |
-
-Only `Selector` has native additions so far. React Native and Android bindings
-are not built yet; see [the experiment matrix](#experiment-matrix).
+| Part           | Path                              | What it does                                                                                                                                                                                                                                                                                                 |
+| -------------- | --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| 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.                                                                 |
+| 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.                                                                                                                                                            |
+| 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). |
+| 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.                                                                                                                                                |
+| Icons          | `NATIVE_ICON_DEFAULTS`            | Astryx's built-in icon names mapped to SF Symbols on Apple platforms and Material Symbols on Android.                                                                                                                                                                                                        |
+| 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:)`.                                                                                     |
+| 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.                                                                    |
+| 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.                                                                                                                                                        |
+
+Contracts cover Badge, Button, Card, Divider, Heading, HStack, ProgressBar,
+Selector, Switch, Text, TextInput, and VStack. The `Astryx` Swift product draws
+Text, Heading, Button, TextInput, Card, and Banner, and `apple/Templates/` the
+`login` template, in SwiftUI.
+React Native and Android bindings are not built yet; see
+[the experiment matrix](#experiment-matrix).
 
 ```ts
 // tsconfig.json for an iOS app: "customConditions": ["ios"]
@@ -34,22 +41,131 @@ const props: SelectorProps = {
 };
 ```
 
+How core documentation becomes a contract:
+
+- A callback whose arguments are values followed by the DOM event that caused
+  them, such as `(checked: boolean, e: ChangeEvent) => void`, keeps the values
+  in the core; the event stays on the web.
+- A callback that carries only an event stays on the web, unless the component
+  names it in `callbacks`, as Button does for `onClick`. Its core form takes no
+  arguments. A callback with an event before a value stays on the web either
+  way.
+- Free-form content becomes a typed slot only where a component declares one
+  in `slots`; `text` is a string, as for a badge's label or a heading's words,
+  and `content` is child Astryx components, as for a stack's or a card's
+  children. A SwiftUI view takes content as a view builder, so `<Name>Props`
+  leaves it out; `<Name>Node` carries it as child nodes.
+- A closed set of numbers, such as a heading level, is a Swift enum with raw
+  values.
+- A core prop may share a platform toolkit's name only when the component
+  declares in `sameMeaning` that it means the same thing there.
+
+### The wire (arm C)
+
+A TypeScript core sends a tree of nodes and receives actions. A node lists the
+callbacks the core listens to in `events`; a view gets only those callbacks.
+
+```ts
+// tsconfig: "customConditions": ["ios"]
+import type {AstryxAction, AstryxNode} from '@astryxdesign/native/components';
+
+const screen: AstryxNode = {
+  component: 'VStack',
+  key: 'root',
+  props: {
+    gap: 2,
+    children: [
+      {
+        component: 'Switch',
+        key: 'wifi',
+        props: {label: 'Wi-Fi', value: true},
+        events: ['onChange'],
+      },
+    ],
+  },
+};
+// What the host sends back when the switch is turned off:
+const action: AstryxAction = {
+  key: 'wifi',
+  component: 'Switch',
+  event: 'onChange',
+  args: [false],
+};
+```
+
+```swift
+let host = AstryxLogicHost(bundle: bundleSource) // calls the bundle's global astryxStart(host)
+if case .switch(let wifi) = host.root {
+  let props = wifi.viewProps(send: host.send)
+}
+```
+
+```ts
+// tsconfig: "customConditions": ["ios"]
+import type {AstryxAction, AstryxNode} from '@astryxdesign/native/components';
+import {connectBridge, createLogicCore} from '@astryxdesign/native/logic';
+import type {Bridge, BridgeHost} from '@astryxdesign/native/logic';
+
+const core = createLogicCore<{wifi: boolean}, AstryxNode, AstryxAction>({
+  initial: {wifi: true},
+  view: state => ({
+    component: 'Switch',
+    key: 'wifi',
+    props: {label: 'Wi-Fi', value: state.wifi},
+    events: ['onChange'],
+  }),
+  reduce: (state, action) =>
+    action.component === 'Switch' && action.event === 'onChange'
+      ? {wifi: action.args[0]}
+      : state,
+});
+// The bundle's entry: the native host calls it with its two calls in and
+// gets back the bridge it reads snapshots from and dispatches actions to.
+(globalThis as {astryxStart?: (host: BridgeHost) => Bridge}).astryxStart =
+  host => connectBridge(core, host);
+```
+
 ## Working on it
 
 ```sh
+pnpm -F @astryxdesign/native typecheck        # source and tests
 pnpm -F @astryxdesign/native build            # dist/, including platform types
+pnpm -F @astryxdesign/native typecheck:types  # every platform's types, after build
 pnpm -F @astryxdesign/native generate:apple   # regenerate apple/Sources/.../Generated
+pnpm -F @astryxdesign/native generate:swift-ios # regenerate the Astryx product's typed tokens, every published theme, and strings
 pnpm vitest run --project node packages/native
 ```
 
 Generated Swift is committed so a Swift package can pin a commit. A test fails
 when it drifts from the contracts.
 
+**Cleanup needed.** Committing the generated Swift
+(`apple/Sources/AstryxNative/Generated`) is temporary. It is there only because
+Swift Package Manager installs a package from a git commit and cannot run the
+Node generator. The intended replacement: CI generates the Swift files and
+publishes them to a Swift-only branch or tag that apps pin, and the generated
+files are ignored on `main`.
+
 Boundaries, checked by `pnpm check:package-boundaries`:
 
 - `@astryxdesign/core` never imports this package.
-- This package's source never imports core. It reads core's documentation
-  files as data at build time.
+- No file in this package, in any folder, imports core, apart from the
+  build-time reads AST-082 FR16 lists until core's portable entry ships: the
+  theme generator in `scripts/` may import `@astryxdesign/core/theme` and
+  `@astryxdesign/core/theme/tokens`; `scripts/swift-ios-strings.mjs` may
+  read core's locale catalogs (`@astryxdesign/core/locales/*.json`); and
+  `scripts/core-docs.mjs` reads core's component documentation and built-in
+  icon names as data.
+- The check reads source text in every folder except `node_modules`, `dist`,
+  `.build`, and `.swiftpm`. It flags any other module specifier that names
+  core (`import`, `require`, `require.resolve`, `import.meta.resolve`, or a
+  relative path into `packages/core`). It also flags a path to core's package,
+  written as adjacent string segments (`'@astryxdesign', 'core'`,
+  `'node_modules', '@astryxdesign/core'`, `'packages', 'core'`) or inside one
+  string (`node_modules/@astryxdesign/core`, `packages/core`). In
+  `scripts/core-docs.mjs` it allows exactly one such path, the `CORE_ROOT`
+  definition, and only the listed reads under `CORE_ROOT`. It does not follow
+  paths computed in other ways.
 
 ## Experiment matrix
 

package/apple/Package.swift

@@ -1,18 +1,41 @@
 // swift-tools-version: 6.0
 // Copyright (c) Meta Platforms, Inc. and affiliates.
 
-// Experimental Astryx for Apple platforms (AST-082). The contract types under
-// Sources/AstryxNative/Generated are generated by `pnpm generate:apple`; do not
-// edit them by hand.
+// Experimental Astryx for Apple platforms (AST-082). Two products:
+// - `Astryx`: SwiftUI views painted with the theme's tokens, the theme
+//   environment, and core's localized messages (Sources/Astryx).
+// - `AstryxNative`: the contract types generated by `pnpm generate:apple`
+//   (Sources/AstryxNative/Generated; do not edit them by hand) and the logic
+//   host.
+// Page templates are a separate package in Templates/, with no products,
+// because they are clone-only source and are never published.
 
 import PackageDescription
 
 let package = Package(
   name: "AstryxNative",
+  defaultLocalization: "en",
   platforms: [.iOS(.v17), .macOS(.v14)],
-  products: [.library(name: "AstryxNative", targets: ["AstryxNative"])],
+  products: [
+    .library(name: "Astryx", targets: ["Astryx"]),
+    .library(name: "AstryxNative", targets: ["AstryxNative"]),
+  ],
   targets: [
     .target(name: "AstryxNative", path: "Sources/AstryxNative"),
+    // Resources holds core's catalog messages per locale, generated.
+    .target(
+      name: "Astryx",
+      dependencies: ["AstryxNative"],
+      path: "Sources/Astryx",
+      // Each component's spec lives beside its view (AST-093 FR1).
+      exclude: ["Icon/Icon.spec.md"],
+      resources: [.process("Resources")]
+    ),
     .testTarget(name: "AstryxNativeTests", dependencies: ["AstryxNative"], path: "Tests/AstryxNativeTests"),
+    .testTarget(
+      name: "AstryxTests", dependencies: ["Astryx"], path: "Tests/AstryxTests",
+      // A tiny image that stands in for an app-shipped icon asset.
+      resources: [.process("Resources")]
+    ),
   ]
 )

package/apple/README.md

@@ -0,0 +1,205 @@
+# Astryx for Apple platforms
+
+> **Experimental. Canary only.** Part of `@astryxdesign/native`. APIs change
+> without notice.
+
+One Swift package with two products:
+
+- **`Astryx`**: SwiftUI views painted with the theme's tokens, the theme
+  environment, and core's localized messages. It is arm A of the AST-082
+  experiment (pure native: platform views painted with Astryx's tokens).
+- **`AstryxNative`**: contract types generated from core's component
+  documentation, the wire a TypeScript logic core sends, and the logic host
+  that runs one (arm C).
+
+Page templates built from the views are a separate package with no products,
+because templates are clone-only and never published.
+
+## Layout
+
+```text
+apple/
+├── Package.swift          # products Astryx and AstryxNative
+├── Sources/
+│   ├── Astryx/            # SwiftUI views (module Astryx)
+│   │   ├── Theme/         # tokens, the theme environment, Dynamic Type
+│   │   │   └── Generated/ # typed tokens and every published theme, generated; do not edit
+│   │   ├── Resources/     # core's messages per locale, generated; do not edit
+│   │   ├── Localization/
+│   │   ├── Icon/          # Icon, Icon.spec.md
+│   │   ├── Text/          # Text
+│   │   ├── Heading/       # Heading
+│   │   ├── Button/        # Button
+│   │   ├── TextInput/     # TextInput
+│   │   ├── Card/          # Card
+│   │   └── Banner/        # Banner
+│   └── AstryxNative/      # contracts, wire, logic host (module AstryxNative)
+│       └── Generated/     # generated; do not edit
+├── Tests/
+│   ├── AstryxTests/
+│   └── AstryxNativeTests/
+└── Templates/             # page templates to copy; its own package, never published
+    ├── Package.swift      # no products; compiles and tests the templates
+    ├── Login/             # LoginTemplate, from `astryx template login`
+    └── Tests/
+```
+
+- **`Sources/Astryx/<Name>/`** holds one folder per component, named as in
+  `packages/core/src/<Name>/`. Each view has core's component name in the
+  `Astryx` module (`Button`, `Text`), which re-exports SwiftUI and the
+  generated contracts, so an app file writes `import Astryx` alone. In a file
+  that also imports SwiftUI, write `Astryx.Button` and `SwiftUI.Button`. A
+  component's parameters use core's prop names
+  and values (`variant: .primary`, `size: .lg`, `isLoading`), so code reads
+  the same across web and native. `Text` and `Heading` take the generated
+  `TextProps` and `HeadingProps`, as AST-093 FR5 asks; the others keep five
+  exceptions, the interim shape FR5 exempts until they move onto the generated
+  contracts:
+  - `Button` takes `action` where core has `onClick`.
+  - `Button` takes `fillsWidth` where core has `width="100%"`.
+  - `Button` takes `icon` as a shared icon name (`"search"`), which the
+    generated `ButtonProps` does not carry yet.
+  - `TextInput` takes a `Binding` where core has `value` and `onChange`.
+  - `Card` takes `padding` as a whole spacing step, so it cannot spell
+    core's `0.5` and `1.5` steps.
+- **`Templates/`** holds one folder per page template, named after the
+  `astryx template` id. Templates are clone-only, as on the web: you copy a
+  template's folder into your app and own it from then on. They are a
+  separate package with no products, so nothing imports them, and
+  `@astryxdesign/native` leaves them out of its npm package. A template is
+  built only from `Astryx` views and SwiftUI layout, and matches the web
+  template's content and states. Rules a template needs, such as validation,
+  live in a plain value type beside the view so tests can check them without a
+  screen.
+
+## Use it
+
+Depend on the `Astryx` product. To start from a template, copy its folder,
+such as `Templates/Login/`, into your app's sources; it then belongs to your
+app.
+
+```swift
+import Astryx
+
+@main
+struct DemoApp: App {
+  var body: some Scene {
+    WindowGroup {
+      LoginTemplate().astryxTheme() // copied from Templates/Login/
+    }
+  }
+}
+```
+
+`astryxTheme(_:)` paints a subtree with a theme; without it, components use
+core's default theme. Either way they follow Dark Mode and the person's text
+size.
+
+## Theme tokens
+
+Components read every color, size, and font from the `astryx` environment
+value, never from a constant of their own. `astryx.tokens` holds the theme's
+tokens in the current mode as typed members (`tokens.color.textPrimary`,
+`tokens.space.s4`, `tokens.font.body.size`), so a misspelled token fails to
+compile. Font tokens come grouped: each type style (`tokens.font.body`,
+`tokens.font.heading1`) holds its `size`, `weight`, and `leading`, and
+`tokens.font.family`, `.size`, and `.weight` hold the scales. Text sizes grow with Dynamic Type. The components still read some
+tokens by core's name (`astryx.color("color-accent")`); moving them onto the
+typed members comes next.
+
+`Icon(.search)` draws a shared icon name as the platform's SF Symbol, at
+core's icon size and color, hidden from VoiceOver unless it has a `label`.
+`IconName` holds every built-in name as a static member; a theme maps a name
+to another symbol or to an image the app ships, or registers a
+`<library>:<name>` name, with
+`Theme(…, icons: ["acme:rocket": "airplane", "close": .assetName("brand.close")])`.
+An asset the app does not ship stops a development build with a message that
+names it, and draws nothing in a release build.
+
+Font families come from the theme's `font-family-*` stacks: the first family
+the device has wins, and a system family such as `-apple-system` or
+`sans-serif` is the system font. Icons use core's shared icon names
+(`success`, `warning`, …), drawn as an SF Symbol by default; a theme replaces
+one with `Theme(…, icons: ["success": "checkmark.seal.fill"])`.
+
+`Sources/Astryx/Theme/Generated/` is written by the Swift theme generator
+(`../specs/swift/library/theme-generator.md`) from core's own resolver, light
+and dark:
+
+- `Tokens.swift`: the typed token surface, from core's token names.
+- One `<Name>Theme.swift` per theme, declaring `Theme.<name>`: core's
+  defaults (`.default`) and every published theme package (`.butter`,
+  `.chocolate`, `.gothic`, `.matcha`, `.neutral`, `.stone`, `.y2k`).
+
+```swift
+LoginTemplate().astryxTheme(.neutral)
+```
+
+Regenerate after a theme or core token change:
+
+```sh
+pnpm -F @astryxdesign/native generate:swift-ios
+```
+
+A product generates its own theme the same way, from its theme's module and
+export:
+
+```sh
+node packages/native/scripts/swift-ios-theme.mjs --theme ./src/acmeTheme.ts#acmeTheme --out ./Sources/Theme
+```
+
+A theme's local tokens are not generated yet; the generator names each one it
+leaves out.
+
+**Fonts.** A theme's font families are carried as data. Astryx never bundles
+a font: a component walks the theme's family list in order and uses the first
+family the app has registered; a system family in the list (such as
+`-apple-system` or `sans-serif`) is the system font, and a list with no
+registered family falls back to the system font. To draw a theme's brand face, bundle and register it
+in the app. Faces the published themes name (body, heading, code):
+
+| Theme        | Faces to bundle                            |
+| ------------ | ------------------------------------------ |
+| `.default`   | none (system fonts)                        |
+| `.butter`    | Outfit, JetBrains Mono                     |
+| `.chocolate` | Albert Sans, Fraunces, JetBrains Mono      |
+| `.gothic`    | Fustat, JetBrains Mono                     |
+| `.matcha`    | DM Sans, Playwrite US Trad, JetBrains Mono |
+| `.neutral`   | Figtree                                    |
+| `.stone`     | Figtree, Montserrat, JetBrains Mono        |
+| `.y2k`       | Poppins, JetBrains Mono                    |
+
+The same command writes
+`Sources/Astryx/Resources/<locale>.lproj/Localizable.strings` from core's
+locale catalogs, so words the components speak to assistive technology, such
+as a loading button's "Loading", follow the person's language. Tests in
+`@astryxdesign/native` fail when either committed output drifts from core.
+
+## Working on it
+
+On a Mac with Xcode or the Swift command-line tools:
+
+```sh
+cd packages/native/apple
+swift test                 # both products
+cd Templates && swift test # templates, against the Astryx product
+```
+
+Both packages also declare macOS 14 so they build and test on a Mac without a
+simulator; iOS 17 is the target. Open `Templates/Package.swift` in Xcode to
+run `LoginTemplate` in an iOS simulator through its preview.
+
+To add a component, create `Sources/Astryx/<Name>/<Name>.swift` declaring
+`<Name>` with core's prop names, writing `SwiftUI.<Name>` wherever it means the
+system type, read its tokens from `astryx`, and add tests under
+`Tests/AstryxTests/`. To add a template, create
+`Templates/<Name>/<Name>Template.swift` from the output of
+`astryx template <id>`, with tests under `Templates/Tests/`.
+
+## Not here yet
+
+- The views do not use the generated contract types in `AstryxNative` yet.
+  Moving them onto those types is how a core prop change reaches Swift.
+- Pixel and behavior parity with the web components has not been measured.
+- Increase Contrast, theme-local tokens, and platform theme entries
+  (`defineNativeTheme`, reserved as `Theme.native`) are not wired in.

package/apple/Sources/Astryx/Banner/Banner.swift

@@ -0,0 +1,80 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import SwiftUI
+
+/// Core's `Banner` statuses.
+public enum AstryxBannerStatus: String, CaseIterable, Sendable {
+  case info
+  case warning
+  case error
+  case success
+
+  /// The shared icon name for this status (AST-082 FR17), drawn as the
+  /// theme's or the platform's symbol for it.
+  var iconName: String { rawValue }
+
+  var groundToken: String {
+    switch self {
+    case .info: "color-accent-muted"
+    case .warning: "color-warning-muted"
+    case .error: "color-error-muted"
+    case .success: "color-success-muted"
+    }
+  }
+
+  var iconToken: String {
+    switch self {
+    case .info: "color-accent"
+    case .warning: "color-warning"
+    case .error: "color-error"
+    case .success: "color-success"
+    }
+  }
+}
+
+/// A message about the page or a section of it. The status sets the color
+/// and icon only; the title must say what happened, because the icon is
+/// decorative to VoiceOver.
+public struct Banner: View {
+  let status: AstryxBannerStatus
+  let title: String
+  let description: String?
+  @Environment(\.astryx) private var astryx
+
+  public init(status: AstryxBannerStatus, title: String, description: String? = nil) {
+    self.status = status
+    self.title = title
+    self.description = description
+  }
+
+  public var body: some View {
+    HStack(alignment: .firstTextBaseline, spacing: astryx.space(2)) {
+      if let icon = astryx.icon(status.iconName) {
+        // Sized with the title so it grows with Dynamic Type.
+        icon.sized(astryx.fontSize("text-body-size", 14))
+          .font(astryx.font(size: "text-body-size", 14, weight: "text-body-weight"))
+          .foregroundStyle(astryx.color(status.iconToken))
+          .accessibilityHidden(true)
+      }
+      VStack(alignment: .leading, spacing: astryx.space(1)) {
+        Text(title, weight: .semibold)
+        if let description {
+          Text(description, color: .secondary)
+        }
+      }
+      .frame(maxWidth: .infinity, alignment: .leading)
+    }
+    .padding(astryx.space(3))
+    .background(
+      RoundedRectangle(cornerRadius: astryx.size("radius-container", 12), style: .continuous)
+        .fill(astryx.color(status.groundToken))
+    )
+    .accessibilityElement(children: .ignore)
+    .accessibilityLabel(SwiftUI.Text(accessibilityText))
+  }
+
+  /// What VoiceOver reads: the title, then the description.
+  var accessibilityText: String {
+    description.map { "\(title), \($0)" } ?? title
+  }
+}

package/apple/Sources/Astryx/Base/BaseProps.swift

@@ -0,0 +1,16 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+extension View {
+  /// Core's base props on a view: `id` names it for UI tests, and `isHidden`
+  /// removes it from layout and from assistive technology, as core's `hidden`
+  /// attribute does.
+  @ViewBuilder func astryxBase(_ base: AstryxBaseProps) -> some View {
+    if base.isHidden == true {
+      EmptyView()
+    } else if let id = base.id {
+      accessibilityIdentifier(id)
+    } else {
+      self
+    }
+  }
+}