@astryxdesign/native 0.7.5-canary.bc40b80 → 0.7.5-canary.c60f571

package/README.md

@@ -19,9 +19,11 @@ rests on evidence.
 | 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.                                                                                                                                        |
+| 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.    |
 
-Contracts cover Button, Divider, Heading, ProgressBar, Selector, Switch, Text,
-and TextInput. React Native and Android bindings are not built yet; see
+Contracts cover Button, Card, Divider, Heading, HStack, ProgressBar, Selector,
+Switch, Text, TextInput, and VStack. React Native and Android bindings are not built yet; see
 [the experiment matrix](#experiment-matrix).
 
 ```ts
@@ -45,12 +47,80 @@ How core documentation becomes a contract:
   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.
+  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 node = try JSONDecoder().decode(AstryxNode.self, from: snapshot)
+if case .switch(let wifi) = node {
+  let props = wifi.viewProps { action in core.dispatch(action.json) }
+}
+```
+
+```ts
+import {connectBridge, createLogicCore} 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,
+});
+// In the app's JavaScript engine: the host reads snapshots and dispatches actions.
+const bridge = connectBridge(core, {
+  connected() {},
+  changed(json) {
+    /* to Swift */
+  },
+});
+```
+
 ## Working on it
 
 ```sh
@@ -62,6 +132,13 @@ 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.

package/apple/Sources/AstryxNative/Generated/AstryxBase.swift

@@ -2,7 +2,7 @@
 public enum AstryxBaseTarget: String, Sendable { case root, trigger, control, container }
 
 /// Base props shared by every platform (AST-082 FR7).
-public struct AstryxBaseProps: Equatable, Sendable {
+public struct AstryxBaseProps: Equatable, Codable, Sendable {
   public var id: String?
   public var isHidden: Bool?
   public init(id: String? = nil, isHidden: Bool? = nil) {

package/apple/Sources/AstryxNative/Generated/AstryxNode.swift

@@ -0,0 +1,66 @@
+// Generated by @astryxdesign/native. Do not edit.
+import Foundation
+
+#if os(iOS) || os(macOS)
+/// One Astryx component in a tree a TypeScript core sends, by its `component` name.
+/// A node this binding cannot read decodes as `unsupported`: an unknown component,
+/// or a known one with a value its enums lack or a required prop missing. An older
+/// app then keeps drawing the rest of a newer core's tree.
+public enum AstryxNode: Decodable, Equatable, Sendable {
+  case button(ButtonNode)
+  case card(CardNode)
+  case divider(DividerNode)
+  case heading(HeadingNode)
+  case hStack(HStackNode)
+  case progressBar(ProgressBarNode)
+  case selector(SelectorNode)
+  case `switch`(SwitchNode)
+  case text(TextNode)
+  case textInput(TextInputNode)
+  case vStack(VStackNode)
+  case unsupported(component: String, key: String)
+
+  public var key: String {
+    switch self {
+    case .button(let node): return node.key
+    case .card(let node): return node.key
+    case .divider(let node): return node.key
+    case .heading(let node): return node.key
+    case .hStack(let node): return node.key
+    case .progressBar(let node): return node.key
+    case .selector(let node): return node.key
+    case .`switch`(let node): return node.key
+    case .text(let node): return node.key
+    case .textInput(let node): return node.key
+    case .vStack(let node): return node.key
+    case .unsupported(_, let key): return key
+    }
+  }
+
+  private enum Keys: String, CodingKey { case component, key }
+
+  public init(from decoder: any Decoder) throws {
+    let container = try decoder.container(keyedBy: Keys.self)
+    let component = try container.decode(String.self, forKey: .component)
+    let key = try container.decode(String.self, forKey: .key)
+    do {
+      switch component {
+      case "Button": self = .button(try ButtonNode(from: decoder))
+      case "Card": self = .card(try CardNode(from: decoder))
+      case "Divider": self = .divider(try DividerNode(from: decoder))
+      case "Heading": self = .heading(try HeadingNode(from: decoder))
+      case "HStack": self = .hStack(try HStackNode(from: decoder))
+      case "ProgressBar": self = .progressBar(try ProgressBarNode(from: decoder))
+      case "Selector": self = .selector(try SelectorNode(from: decoder))
+      case "Switch": self = .`switch`(try SwitchNode(from: decoder))
+      case "Text": self = .text(try TextNode(from: decoder))
+      case "TextInput": self = .textInput(try TextInputNode(from: decoder))
+      case "VStack": self = .vStack(try VStackNode(from: decoder))
+      default: self = .unsupported(component: component, key: key)
+      }
+    } catch {
+      self = .unsupported(component: component, key: key)
+    }
+  }
+}
+#endif

package/apple/Sources/AstryxNative/Generated/AstryxWire.swift

@@ -0,0 +1,67 @@
+// Generated by @astryxdesign/native. Do not edit.
+import Foundation
+
+/// A JSON value: a portable callback argument on its way to the core.
+public enum AstryxValue: Codable, Equatable, Sendable {
+  case null
+  case bool(Bool)
+  case number(Double)
+  case string(String)
+  case array([AstryxValue])
+  case object([String: AstryxValue])
+
+  /// Any portable value (a contract's strings, numbers, enums, and records) as JSON.
+  public init<T: Encodable>(_ value: T) {
+    guard let data = try? JSONEncoder().encode(value),
+          let decoded = try? JSONDecoder().decode(AstryxValue.self, from: data) else {
+      self = .null
+      return
+    }
+    self = decoded
+  }
+
+  public init(from decoder: any Decoder) throws {
+    let container = try decoder.singleValueContainer()
+    if container.decodeNil() { self = .null }
+    else if let value = try? container.decode(Bool.self) { self = .bool(value) }
+    else if let value = try? container.decode(Double.self) { self = .number(value) }
+    else if let value = try? container.decode(String.self) { self = .string(value) }
+    else if let value = try? container.decode([AstryxValue].self) { self = .array(value) }
+    else { self = .object(try container.decode([String: AstryxValue].self)) }
+  }
+
+  public func encode(to encoder: any Encoder) throws {
+    var container = encoder.singleValueContainer()
+    switch self {
+    case .null: try container.encodeNil()
+    case .bool(let value): try container.encode(value)
+    case .number(let value): try container.encode(value)
+    case .string(let value): try container.encode(value)
+    case .array(let value): try container.encode(value)
+    case .object(let value): try container.encode(value)
+    }
+  }
+}
+
+/// A callback a view called: which node, which prop, and its arguments.
+public struct AstryxAction: Codable, Equatable, Sendable {
+  public let key: String
+  public let component: String
+  public let event: String
+  public let args: [AstryxValue]
+
+  public init(key: String, component: String, event: String, args: [AstryxValue]) {
+    self.key = key
+    self.component = component
+    self.event = event
+    self.args = args
+  }
+
+  /// The JSON the core receives.
+  public var json: String {
+    let encoder = JSONEncoder()
+    encoder.outputFormatting = [.sortedKeys, .withoutEscapingSlashes]
+    guard let data = try? encoder.encode(self) else { return "{}" }
+    return String(decoding: data, as: UTF8.self)
+  }
+}

package/apple/Sources/AstryxNative/Generated/Button.swift

@@ -1,16 +1,16 @@
 // Generated by @astryxdesign/native. Do not edit.
-public enum ButtonVariant: String, CaseIterable, Sendable {
+public enum ButtonVariant: String, CaseIterable, Codable, Sendable {
   case primary = "primary"
   case secondary = "secondary"
   case ghost = "ghost"
   case destructive = "destructive"
 }
-public enum ButtonSize: String, CaseIterable, Sendable {
+public enum ButtonSize: String, CaseIterable, Codable, Sendable {
   case sm = "sm"
   case md = "md"
   case lg = "lg"
 }
-public enum ButtonElevation: String, CaseIterable, Sendable {
+public enum ButtonElevation: String, CaseIterable, Codable, Sendable {
   case none = "none"
   case low = "low"
   case med = "med"
@@ -45,6 +45,44 @@ public struct ButtonProps {
     self.base = base
   }
 }
+public struct ButtonNode: Decodable, Equatable, Sendable {
+  public struct Props: Decodable, Equatable, Sendable {
+    public var label: String
+    public var variant: ButtonVariant?
+    public var size: ButtonSize?
+    public var elevation: ButtonElevation?
+    public var isLoading: Bool?
+    public var isInterruptible: Bool?
+    public var isDisabled: Bool?
+    public var tooltip: String?
+    public var href: String?
+  }
+  public let key: String
+  public let base: AstryxBaseProps?
+  public let props: Props
+  /// The callbacks the core listens to, by prop name.
+  public let events: [String]?
+
+  public func listens(_ event: String) -> Bool { events?.contains(event) ?? false }
+
+  /// The contract a Button view takes; its callbacks send actions to the core.
+  public func viewProps(send: @escaping @Sendable (AstryxAction) -> Void) -> ButtonProps {
+    let key = self.key
+    return ButtonProps(
+      label: props.label,
+      variant: props.variant,
+      size: props.size,
+      elevation: props.elevation,
+      isLoading: props.isLoading,
+      isInterruptible: props.isInterruptible,
+      isDisabled: props.isDisabled,
+      tooltip: props.tooltip,
+      onClick: listens("onClick") ? { send(AstryxAction(key: key, component: "Button", event: "onClick", args: [])) } : nil,
+      href: props.href,
+      base: base ?? AstryxBaseProps()
+    )
+  }
+}
 #endif
 #if os(macOS)
 public struct ButtonProps {
@@ -75,4 +113,42 @@ public struct ButtonProps {
     self.base = base
   }
 }
+public struct ButtonNode: Decodable, Equatable, Sendable {
+  public struct Props: Decodable, Equatable, Sendable {
+    public var label: String
+    public var variant: ButtonVariant?
+    public var size: ButtonSize?
+    public var elevation: ButtonElevation?
+    public var isLoading: Bool?
+    public var isInterruptible: Bool?
+    public var isDisabled: Bool?
+    public var tooltip: String?
+    public var href: String?
+  }
+  public let key: String
+  public let base: AstryxBaseProps?
+  public let props: Props
+  /// The callbacks the core listens to, by prop name.
+  public let events: [String]?
+
+  public func listens(_ event: String) -> Bool { events?.contains(event) ?? false }
+
+  /// The contract a Button view takes; its callbacks send actions to the core.
+  public func viewProps(send: @escaping @Sendable (AstryxAction) -> Void) -> ButtonProps {
+    let key = self.key
+    return ButtonProps(
+      label: props.label,
+      variant: props.variant,
+      size: props.size,
+      elevation: props.elevation,
+      isLoading: props.isLoading,
+      isInterruptible: props.isInterruptible,
+      isDisabled: props.isDisabled,
+      tooltip: props.tooltip,
+      onClick: listens("onClick") ? { send(AstryxAction(key: key, component: "Button", event: "onClick", args: [])) } : nil,
+      href: props.href,
+      base: base ?? AstryxBaseProps()
+    )
+  }
+}
 #endif

package/apple/Sources/AstryxNative/Generated/Card.swift

@@ -0,0 +1,117 @@
+// Generated by @astryxdesign/native. Do not edit.
+public enum CardPadding: Double, CaseIterable, Codable, Sendable {
+  case v0 = 0
+  case v0_5 = 0.5
+  case v1 = 1
+  case v1_5 = 1.5
+  case v2 = 2
+  case v3 = 3
+  case v4 = 4
+  case v5 = 5
+  case v6 = 6
+  case v8 = 8
+  case v10 = 10
+}
+public enum CardVariant: String, CaseIterable, Codable, Sendable {
+  case `default` = "default"
+  case transparent = "transparent"
+  case muted = "muted"
+  case blue = "blue"
+  case cyan = "cyan"
+  case gray = "gray"
+  case green = "green"
+  case orange = "orange"
+  case pink = "pink"
+  case purple = "purple"
+  case red = "red"
+  case teal = "teal"
+  case yellow = "yellow"
+}
+public enum CardElevation: String, CaseIterable, Codable, Sendable {
+  case none = "none"
+  case low = "low"
+  case med = "med"
+  case high = "high"
+}
+#if os(iOS)
+public struct CardProps {
+  /// Base props attach to this part on every platform.
+  public static let baseTarget: AstryxBaseTarget = .container
+  public var base: AstryxBaseProps
+  public var padding: CardPadding?
+  public var variant: CardVariant?
+  public var elevation: CardElevation?
+  public init(padding: CardPadding? = nil, variant: CardVariant? = nil, elevation: CardElevation? = nil, base: AstryxBaseProps = AstryxBaseProps()) {
+    self.padding = padding
+    self.variant = variant
+    self.elevation = elevation
+    self.base = base
+  }
+}
+public struct CardNode: Decodable, Equatable, Sendable {
+  public struct Props: Decodable, Equatable, Sendable {
+    public var children: [AstryxNode]?
+    public var padding: CardPadding?
+    public var variant: CardVariant?
+    public var elevation: CardElevation?
+  }
+  public let key: String
+  public let base: AstryxBaseProps?
+  public let props: Props
+  /// The callbacks the core listens to, by prop name.
+  public let events: [String]?
+
+  public func listens(_ event: String) -> Bool { events?.contains(event) ?? false }
+
+  /// The contract a Card view takes; its callbacks send actions to the core.
+  public func viewProps(send: @escaping @Sendable (AstryxAction) -> Void) -> CardProps {
+    return CardProps(
+      padding: props.padding,
+      variant: props.variant,
+      elevation: props.elevation,
+      base: base ?? AstryxBaseProps()
+    )
+  }
+}
+#endif
+#if os(macOS)
+public struct CardProps {
+  /// Base props attach to this part on every platform.
+  public static let baseTarget: AstryxBaseTarget = .container
+  public var base: AstryxBaseProps
+  public var padding: CardPadding?
+  public var variant: CardVariant?
+  public var elevation: CardElevation?
+  public init(padding: CardPadding? = nil, variant: CardVariant? = nil, elevation: CardElevation? = nil, base: AstryxBaseProps = AstryxBaseProps()) {
+    self.padding = padding
+    self.variant = variant
+    self.elevation = elevation
+    self.base = base
+  }
+}
+public struct CardNode: Decodable, Equatable, Sendable {
+  public struct Props: Decodable, Equatable, Sendable {
+    public var children: [AstryxNode]?
+    public var padding: CardPadding?
+    public var variant: CardVariant?
+    public var elevation: CardElevation?
+  }
+  public let key: String
+  public let base: AstryxBaseProps?
+  public let props: Props
+  /// The callbacks the core listens to, by prop name.
+  public let events: [String]?
+
+  public func listens(_ event: String) -> Bool { events?.contains(event) ?? false }
+
+  /// The contract a Card view takes; its callbacks send actions to the core.
+  public func viewProps(send: @escaping @Sendable (AstryxAction) -> Void) -> CardProps {
+    return CardProps(
+      padding: props.padding,
+      variant: props.variant,
+      elevation: props.elevation,
+      base: base ?? AstryxBaseProps()
+    )
+  }
+}
+#endif

package/apple/Sources/AstryxNative/Generated/Divider.swift

@@ -1,9 +1,9 @@
 // Generated by @astryxdesign/native. Do not edit.
-public enum DividerOrientation: String, CaseIterable, Sendable {
+public enum DividerOrientation: String, CaseIterable, Codable, Sendable {
   case horizontal = "horizontal"
   case vertical = "vertical"
 }
-public enum DividerVariant: String, CaseIterable, Sendable {
+public enum DividerVariant: String, CaseIterable, Codable, Sendable {
   case subtle = "subtle"
   case strong = "strong"
 }
@@ -24,6 +24,32 @@ public struct DividerProps {
     self.base = base
   }
 }
+public struct DividerNode: Decodable, Equatable, Sendable {
+  public struct Props: Decodable, Equatable, Sendable {
+    public var orientation: DividerOrientation?
+    public var label: String?
+    public var variant: DividerVariant?
+    public var isFullBleed: Bool?
+  }
+  public let key: String
+  public let base: AstryxBaseProps?
+  public let props: Props
+  /// The callbacks the core listens to, by prop name.
+  public let events: [String]?
+
+  public func listens(_ event: String) -> Bool { events?.contains(event) ?? false }
+
+  /// The contract a Divider view takes; its callbacks send actions to the core.
+  public func viewProps(send: @escaping @Sendable (AstryxAction) -> Void) -> DividerProps {
+    return DividerProps(
+      orientation: props.orientation,
+      label: props.label,
+      variant: props.variant,
+      isFullBleed: props.isFullBleed,
+      base: base ?? AstryxBaseProps()
+    )
+  }
+}
 #endif
 #if os(macOS)
 public struct DividerProps {
@@ -42,4 +68,30 @@ public struct DividerProps {
     self.base = base
   }
 }
+public struct DividerNode: Decodable, Equatable, Sendable {
+  public struct Props: Decodable, Equatable, Sendable {
+    public var orientation: DividerOrientation?
+    public var label: String?
+    public var variant: DividerVariant?
+    public var isFullBleed: Bool?
+  }
+  public let key: String
+  public let base: AstryxBaseProps?
+  public let props: Props
+  /// The callbacks the core listens to, by prop name.
+  public let events: [String]?
+
+  public func listens(_ event: String) -> Bool { events?.contains(event) ?? false }
+
+  /// The contract a Divider view takes; its callbacks send actions to the core.
+  public func viewProps(send: @escaping @Sendable (AstryxAction) -> Void) -> DividerProps {
+    return DividerProps(
+      orientation: props.orientation,
+      label: props.label,
+      variant: props.variant,
+      isFullBleed: props.isFullBleed,
+      base: base ?? AstryxBaseProps()
+    )
+  }
+}
 #endif