A API Que Você Constrói Hoje

Você tornou seu contexto reativo. Os consumidores veem as atualizações quando o estado muda. O encanamento funciona. Mas agora vem um desafio mais sutil: como deve ser a sua API de contexto de fato?

Considere um carrinho de compras. Você poderia expor o array bruto de itens e deixar os consumidores usarem push, splice e mutações como quiserem. Ou poderia fornecer métodos específicos como add(), remove() e updateQuantity(). Ambas as abordagens tornam o carrinho funcional, mas levam a bases de código bem diferentes seis meses depois.

A primeira abordagem é rápida, mas frágil. Qualquer componente pode corromper o estado do carrinho. As regras de negócio ficam espalhadas pela aplicação. A depuração vira arqueologia. A segunda abordagem exige mais reflexão antecipada, mas cria um contrato — uma fronteira clara entre o que o provedor gerencia e o que os consumidores podem fazer.

Este artigo explora esse espaço de design. Você aprenderá quando expor dados somente leitura versus capacidades de leitura/escrita, por que métodos de ação superam o acesso direto ao estado bruto e como construir APIs de contexto que permanecem estáveis à medida que sua aplicação cresce. Ao final, você terá uma estrutura para projetar contextos que sejam poderosos e sustentáveis.

Duas Filosofias de Estado Compartilhado

Quando você fornece contexto, está implicitamente escolhendo quanto controle dar aos consumidores. Essa escolha molda tudo o que vem a seguir.

A Abordagem Somente Leitura

O contexto somente leitura expõe dados sem fornecer nenhum mecanismo para modificá-los. O provedor mantém controle total sobre todas as mudanças de estado:

<!-- UserProvider.svelte -->
<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	let user = $state(null)
	let loading = $state(true)
	let error = $state(null)

	// Only expose reading capabilities
	setContext('user', {
		get current() {
			return user
		},
		get isLoggedIn() {
			return user !== null
		},
		get displayName() {
			return user?.name ?? 'Guest'
		},
		get isLoading() {
			return loading
		},
		get error() {
			return error
		}
	})

	// Provider controls all updates internally
	async function loadUser() {
		loading = true
		error = null

		try {
			const response = await fetch('/api/user')
			if (!response.ok) throw new Error('Failed to load user')
			user = await response.json()
		} catch (e) {
			error = e.message
			user = null
		} finally {
			loading = false
		}
	}

	loadUser()
</script>

{@render children()}

Os consumidores podem ler qualquer propriedade exposta, mas não têm como modificar os dados do usuário:

<!-- UserGreeting.svelte -->
<script>
	import { getContext } from 'svelte'

	const userCtx = getContext('user')
</script>

{#if userCtx.isLoading}
	<p>Loading...</p>
{:else if userCtx.error}
	<p class="error">Error: {userCtx.error}</p>
{:else}
	<p>Welcome back, {userCtx.displayName}!</p>
{/if}

O consumidor exibe as informações do usuário, mas não pode alterá-las. Se você precisar desconectar o usuário ou atualizar seu perfil, essas operações residem no provedor ou em componentes que têm acesso direto aos métodos internos do provedor.

Quando Somente Leitura Faz Sentido

O contexto somente leitura funciona bem em vários cenários. Ao lidar com dados derivados ou calculados — valores computados a partir de outras fontes que os consumidores não devem manipular diretamente. Para configurações que permanecem constantes durante o ciclo de vida da aplicação, como feature flags carregadas na inicialização. Para dados externos buscados de APIs onde a fonte da verdade reside no servidor, não no navegador. Quando prevenir alterações acidentais é crítico porque modificações poderiam quebrar invariantes ou corromper estados relacionados.

O padrão somente leitura impõe um fluxo de dados claro: as informações fluem para baixo a partir do provedor e, se os consumidores precisarem disparar mudanças, eles fazem isso por meio de eventos, callbacks ou outros mecanismos que o provedor suporta explicitamente.

A Abordagem de Leitura/Escrita

O contexto de leitura/escrita fornece tanto capacidades de leitura quanto formas controladas de atualizar o estado:

<!-- ThemeProvider.svelte -->
<script>
	import { setContext } from 'svelte'

	let { initialTheme = 'light', children } = $props()

	let theme = $state(initialTheme)

	setContext('theme', {
		// Reading
		get current() {
			return theme
		},
		get isDark() {
			return theme === 'dark'
		},
		get isLight() {
			return theme === 'light'
		},

		// Writing (controlled mutations)
		set(value) {
			if (value === 'light' || value === 'dark' || value === 'system') {
				theme = value
			}
		},
		toggle() {
			theme = theme === 'light' ? 'dark' : 'light'
		},
		reset() {
			theme = initialTheme
		}
	})

	// Sync to document for CSS
	$effect(() => {
		document.documentElement.setAttribute('data-theme', theme)
	})
</script>

{@render children()}

Agora qualquer consumidor pode ler o tema e disparar atualizações:

<!-- ThemeControls.svelte -->
<script>
	import { getContext } from 'svelte'

	const theme = getContext('theme')
</script>

<div class="theme-controls">
	<button onclick={theme.toggle}>
		{theme.isDark ? '☀️ Switch to Light' : '🌙 Switch to Dark'}
	</button>

	<select value={theme.current} onchange={(e) => theme.set(e.target.value)}>
		<option value="light">Light</option>
		<option value="dark">Dark</option>
		<option value="system">System</option>
	</select>

	<button onclick={theme.reset}>Reset to Default</button>
</div>

A diferença crítica em relação a expor o estado bruto é que os consumidores usam os métodos que você fornece. Eles chamam theme.set('dark'), não theme.current = 'dark'. Essa distinção é enormemente importante.

O Argumento a Favor dos Métodos de Ação

Um dos princípios mais importantes no design de contexto é fornecer métodos de ação em vez de acesso direto ao estado bruto. Essa única decisão determina se seu contexto escalará de forma elegante ou se tornará um fardo de manutenção.

O Problema de Expor o Estado Bruto

Considere o que acontece quando você expõe o estado subjacente diretamente:

<!-- CartProvider.svelte — PROBLEMATIC APPROACH -->
<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	let items = $state([])

	// Exposing raw state directly
	setContext('cart', items)
</script>

{@render children()}

Os consumidores recebem o array e podem fazer qualquer coisa com ele:

<!-- SomeConsumer.svelte -->
<script>
	import { getContext } from 'svelte'

	const cart = getContext('cart')

	function addItem(product) {
		// Direct mutation — works, but...
		cart.push({ ...product, quantity: 1 })
	}

	function clearCart() {
		// Another direct mutation
		cart.length = 0
	}

	function doSomethingWeird() {
		// Also possible!
		cart[0] = { id: 'hacked', price: 0 }
		cart.splice(Math.floor(Math.random() * cart.length), 1)
	}
</script>

Qualquer consumidor pode mutar o array como quiser. Não há validação, nenhuma imposição de lógica de negócio, nenhuma garantia de consistência. Se o seu carrinho tem regras — quantidades máximas, cálculos de preço, verificações de estoque — você não tem um lugar central para impô-las.

A depuração se torna dolorosa porque as mutações podem originar-se de qualquer lugar. Quando o carrinho entra em um estado inválido, você precisa vasculhar cada arquivo que acessa o contexto para encontrar o culpado.

A Solução: Métodos de Ação Controlados

Em vez de expor o estado bruto, exponha um objeto com getters para leitura e métodos para escrita:

<!-- CartProvider.svelte — BETTER APPROACH -->
<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	let items = $state([])

	setContext('cart', {
		// ─── Reading ───────────────────────────────────────
		get items() {
			return items
		},
		get count() {
			return items.reduce((sum, item) => sum + item.quantity, 0)
		},
		get subtotal() {
			return items.reduce((sum, item) => sum + item.price * item.quantity, 0)
		},
		get isEmpty() {
			return items.length === 0
		},

		// ─── Actions ───────────────────────────────────────
		add(product) {
			if (!product?.id || typeof product.price !== 'number') {
				console.warn('Invalid product:', product)
				return false
			}

			const existing = items.find((item) => item.id === product.id)

			if (existing) {
				if (existing.quantity < 99) {
					existing.quantity++
					return true
				}
				return false // Max quantity reached
			}

			items.push({
				id: product.id,
				name: product.name,
				price: product.price,
				quantity: 1
			})
			return true
		},

		remove(productId) {
			const index = items.findIndex((item) => item.id === productId)
			if (index !== -1) {
				items.splice(index, 1)
				return true
			}
			return false
		},

		updateQuantity(productId, quantity) {
			if (typeof quantity !== 'number' || quantity < 0 || quantity > 99) {
				return false
			}

			const item = items.find((i) => i.id === productId)
			if (!item) return false

			if (quantity === 0) {
				return this.remove(productId)
			}

			item.quantity = quantity
			return true
		},

		clear() {
			items.length = 0
		}
	})
</script>

{@render children()}

Agora os consumidores interagem por meio da API definida:

<!-- AddToCartButton.svelte -->
<script>
	import { getContext } from 'svelte'

	let { product } = $props()

	const cart = getContext('cart')

	function handleClick() {
		const success = cart.add(product)
		if (!success) {
			alert('Could not add item to cart')
		}
	}
</script>

<button onclick={handleClick}>Add to Cart</button>

<!-- CartSummary.svelte -->
<script>
	import { getContext } from 'svelte'

	const cart = getContext('cart')
</script>

<div class="cart-summary">
	{#if cart.isEmpty}
		<p>Your cart is empty</p>
	{:else}
		<p>{cart.count} items · ${(cart.subtotal / 100).toFixed(2)}</p>

		{#each cart.items as item (item.id)}
			<div class="cart-item">
				<span>{item.name}</span>
				<input
					type="number"
					min="1"
					max="99"
					value={item.quantity}
					onchange={(e) => cart.updateQuantity(item.id, parseInt(e.target.value))}
				/>
				<button onclick={() => cart.remove(item.id)}>Remove</button>
			</div>
		{/each}

		<button onclick={() => cart.clear()}>Clear Cart</button>
	{/if}
</div>

Por Que as Ações Vencem

Os benefícios se acumulam à medida que sua aplicação cresce.

A validação acontece em um único lugar. O método add verifica se os produtos têm IDs e preços válidos. O método updateQuantity impõe o intervalo de 0 a 99. Os consumidores não precisam se lembrar dessas regras — elas estão incorporadas na API.

A lógica de negócio permanece encapsulada. Se adicionar um item deve também verificar o estoque, registrar analytics ou sincronizar com um servidor, você adiciona essa lógica uma vez no provedor. Todos os consumidores se beneficiam automaticamente.

A depuração se torna manejável. Quando algo dá errado com o carrinho, você examina os métodos de ação. Você pode adicionar logs, breakpoints ou tratamento de erros em um único local.

A refatoração permanece segura. Se você precisar mudar como os itens são armazenados internamente — talvez trocando de array para Map para buscas mais rápidas — os consumidores não precisam mudar. Eles ainda chamam cart.add(product), sem conhecer os detalhes de implementação.

A intenção fica documentada. Nomes de métodos como add, remove e clear descrevem o que o chamador quer realizar. Mutações brutas como items.push() ou items.splice(2, 1) descrevem detalhes de implementação que obscurecem a intenção.

Projetando para a Estabilidade

Uma vez que você publica uma API de contexto, os consumidores dependem dela. Cada getter que eles leem, cada método que eles chamam, torna-se parte do seu contrato. Mudar a API quebra o código deles.

Escolha Nomes que Durem

Nomes de propriedades e métodos devem descrever conceitos, não implementações:

<script>
	// ❌ Too specific — what if you add 'system' or 'auto' themes?
	setContext('theme', {
		get isLight() {
			return theme === 'light'
		},
		get isDark() {
			return theme === 'dark'
		}
	})

	// ✅ More flexible — works with any theme value
	setContext('theme', {
		get current() {
			return theme
		},
		is(value) {
			return theme === value
		}
	})
</script>

A segunda versão lida com valores futuros de tema sem mudanças na API. Os consumidores escrevem theme.is('dark') em vez de theme.isDark, e quando você adiciona um tema 'system', o código existente continua funcionando.

Prefira Mudanças Aditivas

Adicionar novas propriedades e métodos é seguro — o código existente ignora o que não usa. Remover ou renomear quebra os consumidores imediatamente.

<script>
	// Version 1.0
	setContext('cart', {
		get items() {
			return items
		},
		add(product) {
			/* ... */
		},
		remove(id) {
			/* ... */
		}
	})

	// Version 1.1 — SAFE: only additions
	setContext('cart', {
		get items() {
			return items
		},
		get count() {
			return items.length
		}, // New
		get isEmpty() {
			return items.length === 0
		}, // New
		add(product) {
			/* ... */
		},
		addMultiple(products) {
			/* ... */
		}, // New
		remove(id) {
			/* ... */
		},
		clear() {
			/* ... */
		} // New
	})

	// Version 2.0 — BREAKING: renamed method
	setContext('cart', {
		get items() {
			return items
		},
		addItem(product) {
			/* ... */
		} // Was 'add' — breaks all callers!
	})
</script>

Se você precisar fazer mudanças que quebrem compatibilidade, considere manter a API antiga funcionando junto com a nova, pelo menos temporariamente:

<script>
	setContext('cart', {
		// New preferred name
		addItem(product) {
			/* ... */
		},

		// Deprecated but still works
		add(product) {
			console.warn('cart.add() is deprecated, use cart.addItem()')
			return this.addItem(product)
		}
	})
</script>

Trate Casos Extremos Explicitamente

Todo método de ação deve considerar o que acontece com entradas inválidas:

<script>
	setContext('cart', {
		remove(productId) {
			// ❌ Dangerous: splice(-1, 1) removes the LAST item
			const index = items.findIndex((i) => i.id === productId)
			items.splice(index, 1)
		}
	})

	// ✅ Safe: validate before operating
	setContext('cart', {
		remove(productId) {
			const index = items.findIndex((i) => i.id === productId)
			if (index === -1) {
				return false // Item not found
			}
			items.splice(index, 1)
			return true
		}
	})
</script>

A segunda versão lida com o caso de "item não encontrado" explicitamente. Os chamadores podem verificar o valor de retorno se quiserem, ou ignorá-lo se não precisarem. De qualquer forma, o estado do carrinho permanece consistente.

O Contrato Provedor-Consumidor

Pense no contexto como um contrato formal entre duas partes com responsabilidades distintas.

┌─────────────────────────────────────────────────────────────┐
│  PROVIDER RESPONSIBILITIES                                  │
│  ─────────────────────────                                  │
│  • Initialize state with sensible defaults                  │
│  • Validate all inputs to action methods                    │
│  • Maintain data consistency and invariants                 │
│  • Handle side effects (persistence, API calls, logging)    │
│  • Define and document the public API                       │
│  • Ensure getters always return current, valid data         │
└─────────────────────────────────────────────────────────────┘
                              │
                              │ Context Object
                              │ (the contract)
                              ▼
┌─────────────────────────────────────────────────────────────┐
│  CONSUMER RESPONSIBILITIES                                  │
│  ─────────────────────────                                  │
│  • Use only the public API (getters and methods)            │
│  • Trust that getters return current, reactive data         │
│  • Call actions for all mutations                           │
│  • Handle potential failures (check return values)          │
│  • Avoid assumptions about internal implementation          │
└─────────────────────────────────────────────────────────────┘

Essa separação cria uma fronteira clara. O provedor pode mudar sua implementação interna — trocando estruturas de dados, adicionando cache, introduzindo otimizações — sem afetar os consumidores. Os consumidores podem evoluir sua UI e lógica sem se preocupar em corromper o estado compartilhado.

Exemplo Completo: Contexto de Formulário Multi-Etapas

Vamos aplicar esses princípios a um cenário realista: um formulário com múltiplas etapas, com validação, navegação e gerenciamento de envio.

<!-- FormProvider.svelte -->
<script>
	import { setContext } from 'svelte'

	let { steps, initialData = {}, onSubmit, children } = $props()

	// ─── Internal State ────────────────────────────────────
	// Note: initialData is captured at mount time. This is intentional—
	// forms typically don't need to react to prop changes mid-session.
	// The reset() method uses this captured value to restore initial state.
	const capturedInitialData = { ...initialData }
	let formData = $state({ ...capturedInitialData })
	let currentStepIndex = $state(0)
	let fieldErrors = $state({})
	let formError = $state(null)
	let submitting = $state(false)
	let submitted = $state(false)

	// ─── Derived Values ────────────────────────────────────
	let currentStep = $derived(steps[currentStepIndex])
	let isFirstStep = $derived(currentStepIndex === 0)
	let isLastStep = $derived(currentStepIndex === steps.length - 1)
	let hasErrors = $derived(Object.keys(fieldErrors).length > 0)
	let progress = $derived(((currentStepIndex + 1) / steps.length) * 100)

	// ─── Helper Functions ──────────────────────────────────
	function validateCurrentStep() {
		fieldErrors = {}

		if (currentStep.validate) {
			const errors = currentStep.validate(formData)
			if (errors && Object.keys(errors).length > 0) {
				fieldErrors = errors
				return false
			}
		}
		return true
	}

	// ─── Context API ───────────────────────────────────────
	setContext('form', {
		// Reading: Form Data
		get data() {
			return formData
		},
		getField(name) {
			return formData[name] ?? ''
		},

		// Reading: Navigation State
		get currentStep() {
			return currentStep
		},
		get stepIndex() {
			return currentStepIndex
		},
		get stepCount() {
			return steps.length
		},
		get isFirstStep() {
			return isFirstStep
		},
		get isLastStep() {
			return isLastStep
		},
		get progress() {
			return progress
		},

		// Reading: Validation State
		get errors() {
			return fieldErrors
		},
		get formError() {
			return formError
		},
		get hasErrors() {
			return hasErrors
		},
		getError(name) {
			return fieldErrors[name] ?? null
		},

		// Reading: Submission State
		get isSubmitting() {
			return submitting
		},
		get isSubmitted() {
			return submitted
		},

		// Actions: Update Fields
		setField(name, value) {
			formData[name] = value
			// Clear field error when user edits
			if (fieldErrors[name]) {
				delete fieldErrors[name]
			}
			// Clear form-level error on any edit
			formError = null
		},

		setFields(updates) {
			Object.entries(updates).forEach(([name, value]) => {
				formData[name] = value
				if (fieldErrors[name]) {
					delete fieldErrors[name]
				}
			})
			formError = null
		},

		// Actions: Validation
		setFieldError(name, message) {
			if (message) {
				fieldErrors[name] = message
			} else {
				delete fieldErrors[name]
			}
		},

		setFormError(message) {
			formError = message
		},

		clearErrors() {
			fieldErrors = {}
			formError = null
		},

		validateStep() {
			return validateCurrentStep()
		},

		// Actions: Navigation
		nextStep() {
			if (isLastStep) return false
			if (!validateCurrentStep()) return false

			currentStepIndex++
			return true
		},

		prevStep() {
			if (isFirstStep) return false
			currentStepIndex--
			return true
		},

		goToStep(index) {
			if (index < 0 || index >= steps.length) return false
			if (index > currentStepIndex && !validateCurrentStep()) return false

			currentStepIndex = index
			return true
		},

		// Actions: Submission
		async submit() {
			if (submitting || submitted) return false
			if (!validateCurrentStep()) return false

			submitting = true
			formError = null

			try {
				await onSubmit(formData)
				submitted = true
				return true
			} catch (e) {
				formError = e.message || 'Submission failed'
				return false
			} finally {
				submitting = false
			}
		},

		// Actions: Reset
		reset() {
			formData = { ...capturedInitialData }
			currentStepIndex = 0
			fieldErrors = {}
			formError = null
			submitting = false
			submitted = false
		}
	})
</script>

{@render children()}

Agora os consumidores têm uma API clara e abrangente para trabalhar:

<!-- FormProgress.svelte -->
<script>
	import { getContext } from 'svelte'

	const form = getContext('form')
</script>

<div class="progress-container">
	<div class="progress-bar">
		<div class="progress-fill" style="width: {form.progress}%"></div>
	</div>

	<p class="progress-text">
		Step {form.stepIndex + 1} of {form.stepCount}: {form.currentStep.title}
	</p>
</div>

<style>
	.progress-container {
		margin-bottom: 1.5rem;
	}

	.progress-bar {
		height: 4px;
		background: #e5e7eb;
		border-radius: 2px;
		overflow: hidden;
	}

	.progress-fill {
		height: 100%;
		background: #3b82f6;
		transition: width 0.3s ease;
	}

	.progress-text {
		margin-top: 0.5rem;
		font-size: 0.875rem;
		color: #6b7280;
	}
</style>

<!-- FormField.svelte -->
<script>
	import { getContext } from 'svelte'

	let { name, label, type = 'text', required = false } = $props()

	const form = getContext('form')

	let error = $derived(form.getError(name))
	let value = $derived(form.getField(name))
</script>

<div class="field" class:has-error={error}>
	<label for={name}>
		{label}
		{#if required}<span class="required">*</span>{/if}
	</label>

	<input
		id={name}
		{type}
		{value}
		oninput={(e) => form.setField(name, e.target.value)}
		aria-invalid={error ? 'true' : undefined}
		aria-describedby={error ? `${name}-error` : undefined}
	/>

	{#if error}
		<p id="{name}-error" class="error-message">{error}</p>
	{/if}
</div>

<style>
	.field {
		margin-bottom: 1rem;
	}

	label {
		display: block;
		margin-bottom: 0.25rem;
		font-weight: 500;
		color: #374151;
	}

	.required {
		color: #ef4444;
		margin-left: 0.25rem;
	}

	input {
		width: 100%;
		padding: 0.625rem 0.75rem;
		border: 1px solid #d1d5db;
		border-radius: 6px;
		font-size: 1rem;
		transition:
			border-color 0.15s,
			box-shadow 0.15s;
	}

	input:focus {
		outline: none;
		border-color: #3b82f6;
		box-shadow: 0 0 0 3px rgba(59, 130, 246, 0.1);
	}

	.has-error input {
		border-color: #ef4444;
	}

	.has-error input:focus {
		box-shadow: 0 0 0 3px rgba(239, 68, 68, 0.1);
	}

	.error-message {
		margin-top: 0.25rem;
		font-size: 0.875rem;
		color: #ef4444;
	}
</style>

<!-- FormNavigation.svelte -->
<script>
	import { getContext } from 'svelte'

	const form = getContext('form')
</script>

<div class="navigation">
	{#if !form.isFirstStep}
		<button type="button" onclick={() => form.prevStep()} class="btn-secondary"> ← Back </button>
	{/if}

	<div class="spacer"></div>

	{#if form.isLastStep}
		<button
			type="button"
			onclick={() => form.submit()}
			disabled={form.isSubmitting}
			class="btn-primary"
		>
			{form.isSubmitting ? 'Submitting...' : 'Submit'}
		</button>
	{:else}
		<button type="button" onclick={() => form.nextStep()} class="btn-primary"> Next → </button>
	{/if}
</div>

{#if form.formError}
	<div class="form-error" role="alert">
		<p>{form.formError}</p>
	</div>
{/if}

<style>
	.navigation {
		display: flex;
		gap: 1rem;
		margin-top: 1.5rem;
		padding-top: 1.5rem;
		border-top: 1px solid #e5e7eb;
	}

	.spacer {
		flex: 1;
	}

	button {
		padding: 0.625rem 1.25rem;
		border: none;
		border-radius: 6px;
		font-weight: 500;
		font-size: 0.9375rem;
		cursor: pointer;
		transition: background-color 0.15s;
	}

	button:disabled {
		opacity: 0.5;
		cursor: not-allowed;
	}

	.btn-primary {
		background: #3b82f6;
		color: white;
	}

	.btn-primary:hover:not(:disabled) {
		background: #2563eb;
	}

	.btn-secondary {
		background: #f3f4f6;
		color: #374151;
	}

	.btn-secondary:hover:not(:disabled) {
		background: #e5e7eb;
	}

	.form-error {
		margin-top: 1rem;
		padding: 0.75rem 1rem;
		background: #fef2f2;
		border: 1px solid #fecaca;
		border-radius: 6px;
	}

	.form-error p {
		margin: 0;
		color: #dc2626;
		font-size: 0.875rem;
	}
</style>

<!-- FormStepContent.svelte -->
<script>
	import { getContext } from 'svelte'
	import FormField from './FormField.svelte'

	const form = getContext('form')
</script>

{#if form.currentStep.id === 'personal'}
	<FormField name="name" label="Full Name" required />
	<FormField name="email" label="Email Address" type="email" required />
	<FormField name="phone" label="Phone Number" type="tel" />
{:else if form.currentStep.id === 'address'}
	<FormField name="street" label="Street Address" required />
	<FormField name="city" label="City" required />
	<FormField name="state" label="State / Province" />
	<FormField name="zip" label="ZIP / Postal Code" />
{:else if form.currentStep.id === 'review'}
	<div class="review-section">
		<h3>Review Your Information</h3>
		<dl class="review-list">
			<div class="review-item">
				<dt>Name</dt>
				<dd>{form.data.name || '—'}</dd>
			</div>
			<div class="review-item">
				<dt>Email</dt>
				<dd>{form.data.email || '—'}</dd>
			</div>
			<div class="review-item">
				<dt>Phone</dt>
				<dd>{form.data.phone || '—'}</dd>
			</div>
			<div class="review-item">
				<dt>Address</dt>
				<dd>
					{#if form.data.street}
						{form.data.street}<br />
						{form.data.city}{form.data.state ? `, ${form.data.state}` : ''}
						{form.data.zip || ''}
					{:else}
						—
					{/if}
				</dd>
			</div>
		</dl>
	</div>
{/if}

<style>
	.review-section h3 {
		margin: 0 0 1rem;
		font-size: 1.125rem;
		color: #1f2937;
	}

	.review-list {
		margin: 0;
	}

	.review-item {
		display: grid;
		grid-template-columns: 120px 1fr;
		gap: 0.5rem;
		padding: 0.75rem 0;
		border-bottom: 1px solid #e5e7eb;
	}

	.review-item:last-child {
		border-bottom: none;
	}

	dt {
		font-weight: 500;
		color: #6b7280;
	}

	dd {
		margin: 0;
		color: #1f2937;
	}
</style>

Juntando tudo:

<!-- src/routes/register/+page.svelte -->
<script>
	import FormProvider from '$lib/components/FormProvider.svelte'
	import FormProgress from '$lib/components/FormProgress.svelte'
	import FormStepContent from '$lib/components/FormStepContent.svelte'
	import FormNavigation from '$lib/components/FormNavigation.svelte'

	const steps = [
		{
			id: 'personal',
			title: 'Personal Information',
			validate(data) {
				const errors = {}
				if (!data.name?.trim()) {
					errors.name = 'Name is required'
				}
				if (!data.email?.trim()) {
					errors.email = 'Email is required'
				} else if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(data.email)) {
					errors.email = 'Please enter a valid email address'
				}
				return Object.keys(errors).length > 0 ? errors : null
			}
		},
		{
			id: 'address',
			title: 'Address',
			validate(data) {
				const errors = {}
				if (!data.street?.trim()) {
					errors.street = 'Street address is required'
				}
				if (!data.city?.trim()) {
					errors.city = 'City is required'
				}
				return Object.keys(errors).length > 0 ? errors : null
			}
		},
		{
			id: 'review',
			title: 'Review & Submit',
			validate: null
		}
	]

	async function handleSubmit(data) {
		// Simulate API call
		await new Promise((resolve) => setTimeout(resolve, 1500))
		console.log('Registration complete:', data)
	}
</script>

<div class="page">
	<h1>Create Account</h1>

	<FormProvider {steps} onSubmit={handleSubmit}>
		<div class="form-container">
			<FormProgress />
			<FormStepContent />
			<FormNavigation />
		</div>
	</FormProvider>
</div>

<style>
	.page {
		max-width: 500px;
		margin: 2rem auto;
		padding: 0 1rem;
	}

	h1 {
		margin: 0 0 1.5rem;
		font-size: 1.75rem;
		color: #1f2937;
		text-align: center;
	}

	.form-container {
		padding: 1.5rem;
		background: white;
		border-radius: 12px;
		box-shadow:
			0 1px 3px rgba(0, 0, 0, 0.1),
			0 1px 2px rgba(0, 0, 0, 0.06);
	}
</style>

Este exemplo demonstra todos os princípios que discutimos. O provedor gerencia todo o estado internamente. Os consumidores utilizam uma API limpa de getters e métodos de ação. A validação acontece de forma centralizada. A navegação protege contra progressão inválida. A API é compatível com extensões e documenta sua intenção por meio dos nomes dos métodos.

Erros Comuns e Como Evitá-los

1: Expor Setters Brutos Sem Validação

<script>
	let count = $state(0)

	// ❌ No validation — consumers can set anything
	setContext('counter', {
		get value() {
			return count
		},
		set value(v) {
			count = v
		}
	})
</script>

Os consumidores podem definir números negativos, strings ou undefined. Em vez disso, forneça métodos de ação explícitos:

<script>
	setContext('counter', {
		get value() {
			return count
		},
		increment() {
			count++
		},
		decrement() {
			if (count > 0) count--
		},
		set(v) {
			if (typeof v === 'number' && v >= 0 && Number.isFinite(v)) {
				count = Math.floor(v)
			}
		}
	})
</script>

2: Não Tratar Casos Extremos nos Métodos de Ação

<script>
	// ❌ Dangerous when item doesn't exist
	setContext('list', {
		remove(id) {
			const index = items.findIndex((i) => i.id === id)
			items.splice(index, 1) // splice(-1, 1) removes last item!
		}
	})
</script>

Sempre valide antes de operar:

<script>
	setContext('list', {
		remove(id) {
			const index = items.findIndex((i) => i.id === id)
			if (index !== -1) {
				items.splice(index, 1)
				return true
			}
			return false
		}
	})
</script>

3: Misturar Retornos Somente Leitura e Mutáveis

<script>
	// ❌ Confusing: items getter returns mutable array
	setContext('cart', {
		get items() {
			return items
		} // Consumers can still mutate!
	})
</script>

Se você deseja um comportamento verdadeiramente somente leitura, retorne uma cópia:

<script>
	setContext('cart', {
		get items() {
			return [...items]
		}, // New array each time
		get itemCount() {
			return items.length
		}
	})
</script>

Observe que retornar cópias tem implicações de desempenho para arrays grandes ou acessos frequentes. Escolha com base nas suas necessidades específicas.

Considerações de Desempenho e Escalabilidade

O design da API de contexto impacta o desempenho conforme sua aplicação cresce. Entender esses trade-offs ajuda você a tomar decisões informadas.

Frequência de Avaliação dos Getters

Os getters no seu objeto de contexto são executados toda vez que são acessados. Para retornos simples de propriedades, essa sobrecarga é negligenciável. No entanto, para computações custosas, prefira valores $derived que armazenam os resultados em cache até que as dependências mudem:

<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	let items = $state([])

	// ❌ Recalculates on every access
	setContext('cart-inefficient', {
		get total() {
			return items.reduce((sum, item) => {
				return sum + calculateComplexTotal(item) // Expensive operation
			}, 0)
		}
	})

	// ✅ Caches result until items change
	let total = $derived(items.reduce((sum, item) => sum + calculateComplexTotal(item), 0))

	setContext('cart-efficient', {
		get total() {
			return total
		}
	})

	function calculateComplexTotal(item) {
		// Simulates expensive calculation
		return item.price * item.quantity * (1 - (item.discount || 0))
	}
</script>

{@render children()}

A primeira abordagem recalcula a cada acesso a cart.total. A segunda calcula uma vez quando items muda e, em seguida, retorna o valor em cache.

Tamanho do Objeto de Contexto

Objetos de contexto grandes com muitos métodos não impactam o desempenho de forma inerente — objetos JavaScript são baratos de criar e acessar. No entanto, considere estes fatores:

Estados reativos profundamente aninhados exigem um rastreamento mais granular pelo sistema de reatividade do Svelte. Mantenha as estruturas de estado razoavelmente planas sempre que possível. Um array de objetos com algumas propriedades cada é adequado; árvores de objetos profundamente aninhadas podem se beneficiar de normalização.

Se o seu contexto tem dezenas de métodos de ação, considere se ele está fazendo coisas demais. Um contexto de formulário com 15 métodos é razoável. Um "contexto deus" com 50 métodos gerenciando questões não relacionadas provavelmente deveria ser dividido em múltiplos contextos focados.

Efeitos Colaterais dos Métodos de Ação

Métodos de ação que disparam requisições de rede, computações pesadas ou gravações no localStorage devem considerar debounce ou agrupamento (batching). O provedor de contexto é um excelente lugar para centralizar tais otimizações, já que todas as mutações passam por ele:

<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	let preferences = $state({})
	let saveTimeout = null

	function debouncedSave() {
		clearTimeout(saveTimeout)
		saveTimeout = setTimeout(() => {
			localStorage.setItem('preferences', JSON.stringify(preferences))
		}, 500)
	}

	setContext('preferences', {
		get all() {
			return preferences
		},
		set(key, value) {
			preferences[key] = value
			debouncedSave() // Batches rapid changes
		}
	})
</script>

{@render children()}

Os consumidores chamam preferences.set() livremente sem se preocupar com desempenho — o provedor lida com a otimização de forma transparente.

Quando NÃO Usar Este Padrão

APIs de contexto baseadas em métodos de ação se destacam em muitos cenários, mas nem sempre são a escolha certa.

Compartilhamento de Valores Simples

Se você está compartilhando um único valor simples que não requer validação ou lógica de negócio complexa, a cerimônia dos métodos de ação adiciona complexidade sem benefício proporcional:

<script>
	import { setContext } from 'svelte'

	let { children } = $props()

	let locale = $state('en')

	// For a simple locale setting, this might be overkill:
	setContext('locale-verbose', {
		get current() {
			return locale
		},
		setEnglish() {
			locale = 'en'
		},
		setSpanish() {
			locale = 'es'
		},
		setFrench() {
			locale = 'fr'
		},
		set(value) {
			if (['en', 'es', 'fr'].includes(value)) {
				locale = value
			}
		}
	})

	// Sometimes simpler is better:
	setContext('locale-simple', {
		get value() {
			return locale
		},
		set(v) {
			locale = v
		}
	})
</script>

{@render children()}

A versão mais simples é mais fácil de entender e suficiente para casos de uso diretos. Reserve o padrão completo de métodos de ação para estados que genuinamente se beneficiam do encapsulamento.

Prop Drilling Às Vezes É Adequado

O contexto resolve o problema de prop drilling, mas árvores de componentes rasas não precisam dessa solução. Se você está passando dados por dois ou três níveis, props explícitas costumam ser mais claras e rastreáveis:

<!-- Passing through 2-3 levels? Props are fine. -->
<Parent>
	<Child {user}>
		<Grandchild {user} />
	</Child>
</Parent>

<!-- Passing through 5+ levels? Consider context. -->

Props tornam o fluxo de dados explícito. Você pode rastrear de onde os dados vêm lendo a hierarquia de componentes. O contexto oculta esse fluxo, o que é valioso para estado amplamente compartilhado, mas adiciona sobrecarga cognitiva para casos simples.

Estado Local do Componente

Estado que apenas um componente utiliza não deveria estar no contexto. O contexto é para estado genuinamente compartilhado — dados que múltiplos componentes, potencialmente distantes entre si, precisam coordenar.

O estado aberto/fechado de um modal, erros de validação locais de um formulário, o valor de progresso de uma animação — esses pertencem ao $state local do componente, não ao contexto. Colocar tudo no contexto cria acoplamento desnecessário e torna os componentes mais difíceis de reutilizar.

Conjuntos de Consumidores Altamente Dinâmicos

Se os componentes que consomem seu contexto montam e desmontam rapidamente (como itens em uma lista virtualizada), certifique-se de que sua API de contexto não cria closures ou assinaturas que possam causar problemas de memória. O padrão baseado em getters descrito neste artigo lida bem com isso, mas seja cauteloso com padrões que registram callbacks ou listeners.

Principais Conclusões

O design da API de contexto molda como sua aplicação evolui. As decisões que você toma cedo—somente leitura versus leitura e escrita, estado bruto versus métodos de ação—se acumulam ao longo do tempo em uma arquitetura sustentável ou em uma teia emaranhada de dependências implícitas.

Escolha somente leitura quando apropriado. Configurações, dados derivados e informações de fontes externas frequentemente não devem ser modificadas pelos consumidores. O contexto somente leitura torna o fluxo de dados explícito e evita corrupção acidental.

Forneça ações, não estado bruto. Métodos de ação como add(), remove() e update() encapsulam validação, lógica de negócio e efeitos colaterais. Eles documentam a intenção, simplificam a depuração e permitem refatoração interna sem quebrar os consumidores.

Projete para estabilidade desde o início. Escolha nomes que não precisarão ser alterados. Prefira mudanças aditivas em vez de modificações. Trate casos extremos explicitamente em cada método de ação.

Respeite o contrato provedor-consumidor. Provedores inicializam, validam e gerenciam o estado. Consumidores utilizam a API pública. Essa separação cria uma fronteira clara que escala junto com sua aplicação.

O esforço que você investe no design da sua API de contexto rende dividendos toda vez que um novo componente precisa interagir com o estado compartilhado. Uma API bem projetada guia os consumidores para o uso correto e os afasta de bugs sutis. Ela torna sua base de código mais previsível, mais testável e mais agradável de trabalhar.

O Que Vem a Seguir

Com o design limpo de API dominado, explore práticas profissionais para contexto em Boas Práticas de Contexto, cobrindo convenções de nomenclatura, organização de arquivos, estratégias de teste e considerações de desempenho.

Veja Também

Documentação Oficial

Svelte Context — Guia oficial de contexto
$state — Rune de estado reativo