projectedValue y el dólar: la segunda cara del wrapper

Un wrapper que solo sepa devolver el valor envuelto es un filtro y poco más. La pieza que lo convierte en un mecanismo de diseño es projectedValue: una segunda propiedad, de tipo libre, que el wrapper puede exponer junto al valor y a la que se accede con el nombre precedido de un signo de dólar. Con ella, una sola declaración pasa a ofrecer dos superficies distintas —el valor para quien solo quiere leerlo o escribirlo, y algo más rico para quien necesita operar sobre el acceso mismo— sin que el tipo contenedor tenga que declarar nada extra. Es, además, la respuesta a una pregunta que todo el mundo se hace al empezar con SwiftUI y casi nadie llega a responderse: de dónde sale el dólar.

Una propiedad, tres nombres

Cuando aplicas un wrapper, el compilador pone a tu disposición hasta tres identificadores distintos para una sola declaración:

@propertyWrapper
struct Acotado {
    private var valor: Int
    private let rango: ClosedRange<Int>
    private(set) var seRecorto = false

    init(wrappedValue: Int, _ rango: ClosedRange<Int>) {
        self.rango = rango
        self.valor = min(max(wrappedValue, rango.lowerBound), rango.upperBound)
    }

    var wrappedValue: Int {
        get { valor }
        set {
            seRecorto = !rango.contains(newValue)
            valor = min(max(newValue, rango.lowerBound), rango.upperBound)
        }
    }

    var projectedValue: Bool { seRecorto }
}

struct Ajustes {
    @Acotado(0...10) var volumen = 5
}

var a = Ajustes()
a.volumen = 99
print(a.volumen)     // 10   -> wrappedValue
print(a.$volumen)    // true -> projectedValue

El reparto es limpio: volumen es el valor envuelto, $volumen es la proyección, y _volumen —accesible solo dentro del tipo— es la instancia del wrapper completa. La visibilidad tampoco es simétrica: el almacenamiento con guion bajo nace private, mientras que la proyección adopta el mismo nivel de acceso que la propiedad original, de modo que forma parte de tu API pública en cuanto la declares. Elegir qué proyectar es, por tanto, una decisión de diseño de interfaz, no un detalle interno.

Proyectar lo que haga falta

projectedValue no tiene ninguna restricción de tipo. Puede ser un dato auxiliar, como el Bool anterior; puede ser un objeto rico; puede ser el propio wrapper. Ese último caso, projectedValue devolviendo self, es más útil de lo que parece: entrega al llamante toda la maquinaria mientras el nombre sin adornos sigue entregando solo el valor.

@propertyWrapper
struct Validado {
    private var valor: String
    private let regla: (String) -> Bool

    init(wrappedValue: String, _ regla: @escaping (String) -> Bool) {
        self.valor = wrappedValue
        self.regla = regla
    }

    var wrappedValue: String {
        get { valor }
        set { valor = newValue }
    }

    var projectedValue: Resultado {
        Resultado(esValido: regla(valor), valor: valor)
    }

    struct Resultado {
        let esValido: Bool
        let valor: String
    }
}

struct Registro {
    @Validado({ $0.contains("@") }) var correo = ""
}

var r = Registro()
r.correo = "hola"
print(r.$correo.esValido)   // false

El patrón que emerge es siempre el mismo: el valor responde a la pregunta cuánto vale, y la proyección responde a preguntas sobre el valor —si es válido, si cambió, quién puede modificarlo, cómo observarlo. Dos preguntas de naturaleza distinta que en un tipo normal exigirían dos propiedades declaradas a mano y mantenidas en sincronía.

flowchart TB
decl[Una sola declaracion con atributo] --> tres[El compilador sintetiza tres nombres]
tres --> a[nombre devuelve wrappedValue]
tres --> b[dolar nombre devuelve projectedValue]
tres --> c[guion bajo nombre es la instancia del wrapper y es privada]
a --> uso1[Para quien solo quiere el valor]
b --> uso2[Para quien opera sobre el acceso al valor]
c --> uso3[Para el codigo interno del tipo]
style decl fill:#cba6f7,color:#11111b
style tres fill:#89b4fa,color:#11111b
style b fill:#a6e3a1,color:#11111b

De dónde sale el dólar de SwiftUI

Con esto ya puedes desmontar la construcción más repetida de SwiftUI. Cuando escribes una vista con estado y pasas el nombre con dólar a un campo de texto, no está ocurriendo nada específico del framework:

struct Formulario: View {
    @State private var texto = ""

    var body: some View {
        VStack {
            TextField("Nombre", text: $texto)
            Text("Has escrito: \(texto)")
        }
    }
}

texto es un String porque State declara wrappedValue de tipo Valor. Y $texto es un Binding de String porque State declara projectedValue de tipo Binding, ni más ni menos. TextField pide un Binding porque necesita escribir en el estado, no solo leerlo, y un String copiado no le serviría de nada. El dólar no es sintaxis de SwiftUI: es la sintaxis del lenguaje para pedirle a un wrapper su segunda cara, y SwiftUI se limita a haber elegido bien qué poner en esa cara.

El mismo mecanismo explica el resto de la familia sin necesidad de reglas nuevas. En Combine, @Published proyecta un publicador, y por eso $modelo.contador es algo a lo que puedes suscribirte. @FocusState proyecta un enlace al foco. @Bindable proyecta enlaces hacia las propiedades de un objeto observable. Tres frameworks, cero sintaxis adicional: solo tipos distintos en projectedValue.

Volver a envolver la proyección

Falta una simetría. Si un wrapper puede construirse desde un valor con init(wrappedValue:), también puede construirse desde una proyección con init(projectedValue:). Eso importa desde que Swift permite aplicar wrappers a los parámetros de una función: quien llama puede pasar directamente el nombre con dólar y el compilador reconstruye el wrapper del otro lado.

struct Contador: View {
    @Binding var valor: Int
    var body: some View { Stepper("Valor: \(valor)", value: $valor) }
}

struct Padre: View {
    @State private var n = 0
    // La proyeccion de n es un Binding y Contador la recibe tal cual
    var body: some View { Contador(valor: $n) }
}

Ese es el punto exacto donde el estado deja de estar encerrado en una vista y empieza a circular por el árbol: la proyección es transportable, el valor no. Un String pasado a un hijo es una copia muerta; un Binding de String es una copia del permiso de escritura sobre la ubicación original.