SDK: Core JS + React/Vue/Svelte + Web Component

[BleedingDev]

Goal

Make Smart Address easy to integrate into checkout/onboarding forms across popular frontend stacks, with minimal integration work and consistent user experience.

Who Uses This

• Product teams adding address autocomplete to web forms.
• Frontend developers integrating Smart Address into existing apps (framework or no-framework).
• Designers needing a themeable autocomplete UI.

What “Done” Means (Business)

• A minimal JS SDK exists for any web app.
• First-class adapters exist for React, Vue, and Svelte.
• A Web Component exists for drop‑in usage without framework coupling.
• The autocomplete UX is accessible and consistent (keyboard support, clear selection behavior).
• Integrations make it easy to choose the desired mode (fast vs reliable vs premium) and pass optional context for grouping sessions.
• Documentation provides copy‑paste examples for each integration path.

Constraints

• Start simple/minimal: autocomplete + suggestions only.
• Stable public API surface so integrations don’t churn.
• Keep the component easy to style to match customer brands.

Out of Scope

• Billing/authentication and entitlements.
• Acceptance tracking/analytics events.
• Release automation/publishing workflows.

---

Technical notes: #1 (comment)

MVP Breakdown

• SDK (MVP): publish npm package + global script build (unpkg/jsdelivr) #10
• SDK (MVP): legacy integration example (PHP + Bootstrap + vanilla JS) #11

[coderabbitai]

📝 CodeRabbit Plan Mode

Generate an implementation plan and prompts that you can use with your favorite coding agent.

• Create Plan

Examples

• Example 1
• Example 2

---

🔗 Similar Issues

Related Issues

• Self-hosting: Bun + Docker Alpine #6
• Analytics + monitoring + dashboard (suggested/accepted, cache, providers) #3
• Providers: add HERE + Radar (MVP capacity & benchmarking) #7
• Own address DB + cache improvements (reduce provider dependency) #2

👤 Suggested Assignees

• BleedingDev

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[BleedingDev]

Technical Notes

Proposed Packages

• packages/sdk-core (@smart-address/sdk-core): lightweight HTTP client + shared types.
• packages/sdk-react (@smart-address/sdk-react): React hook + optional input/autocomplete component.
• packages/sdk-vue (@smart-address/sdk-vue): Vue composable + component.
• packages/sdk-svelte (@smart-address/sdk-svelte): Svelte store/action + optional component.
• packages/web-component (@smart-address/web-component): <smart-address-autocomplete> custom element.

Core Client Surface

• createSmartAddressClient({ baseUrl, fetch?, headers? })
• client.suggest({ text, limit?, countryCode?, locale?, sessionToken?, strategy? })

API Contract Mapping

Client params map directly to existing service payload (packages/rpc/src/suggest.ts):

• text/q
• limit
• countryCode
• locale
• sessionToken
• strategy (fast | reliable | future reliable-fast)

Caching / Typing UX (optional but recommended)

A shared client-side cache avoids spamming the API while the user types.

• Use @tanstack/query-core in sdk-core to offer query options.
• Framework packages use the corresponding TanStack bindings.

Web Component

• Tag: <smart-address-autocomplete>
• Attributes/properties: base-url, strategy, limit, country-code, locale, session-token
• Events:
  • smartaddress:select (selected suggestion)
  • smartaddress:error
• A11y: ARIA combobox pattern + keyboard navigation.
• Styling: Shadow DOM + CSS variables (font, colors, radius, shadow).

Guardrails

• Avoid Effect in browser bundles.
• No barrel files.
• Keep SSR-safe (no unconditional window access in core).

[coderabbitai]

Coding Plan

Approach

Create a framework-agnostic JavaScript SDK for Smart Address that provides autocomplete functionality across React, Vue, Svelte, and vanilla JavaScript applications. The SDK will consist of a shared core HTTP client with caching, framework-specific wrapper packages with idiomatic APIs, and a Web Component for drop-in usage, all with accessible autocomplete UI patterns.

Observations

The project is a pnpm monorepo with three existing package types: @smart-address/core (address domain models), @smart-address/integrations (HTTP clients), and @smart-address/rpc (RPC contracts). All packages use rslib for building, follow subpath export patterns, and maintain strict TypeScript configurations with ES2022 targets. The service exposes a suggest endpoint via HTTP and RPC with comprehensive request validation, two-tier caching, and consistent response formats. Documentation uses Rspress with a structured four-tier organization (tutorials, how-to, explanation, reference). The landing app demonstrates basic autocomplete patterns with React and Tailwind CSS but lacks reusable SDK components.

Assumptions

Assumption 1: Caching Strategy in Core Package

Options Considered:

• Implement custom debouncing/caching logic in the core client
• Use TanStack Query Core as recommended in the ticket
• Provide no caching and let consumers handle it

Chosen Option: Use TanStack Query Core as recommended in the ticket

Rationale: Use TanStack Query Core as specified in the technical notes. This provides mature, battle-tested caching with request deduplication, stale-while-revalidate patterns, and SSR support. It's lightweight when used without framework bindings, and framework packages can leverage their respective TanStack Query implementations for deeper integration. This reduces maintenance burden and gives developers familiar APIs.

Assumption 2: Component Complexity Level

Options Considered:

• Build fully-featured components with extensive customization options in Phase 1
• Build minimal, opinionated components that cover 80% use case
• Provide only headless hooks/composables, no components

Chosen Option: Build minimal, opinionated components that cover 80% use case

Rationale: Build minimal, opinionated components with basic theming support. Start with a simple autocomplete that handles keyboard navigation, selection, and basic styling via CSS variables or Tailwind-compatible classes. Advanced customization (custom renderers, complex filtering) can be added in future iterations based on actual developer feedback. This aligns with "start simple/minimal" and gets something working developers can actually ship with.

💡 User Tips

Regenerate the plan with different choices with @coderabbitai <feedback>.

Implementation Steps

Phase 1: Core SDK Package

Create the framework-agnostic foundation in packages/sdk-core that all other SDK packages will consume.

Task 1: Package Setup and Configuration

Set up the new packages/sdk-core package structure with build tooling and TypeScript configuration.

• Create packages/sdk-core/package.json with package name @smart-address/sdk-core, rslib build configuration, and exports for the main entry point (./dist/index.js)
• Create packages/sdk-core/tsconfig.json extending root tsconfig with rootDir: src and ES2022 target
• Add dependencies: TanStack Query Core for caching, type definitions for fetch API
• Update root tsconfig.json to include path alias mapping @smart-address/sdk-core to packages/sdk-core/src/index.ts

Task 2: Type Definitions

Define TypeScript types aligned with the RPC contract for SDK consumers.

• Create packages/sdk-core/src/types.ts to export types for SmartAddressConfig, SuggestAddressParams (matching SuggestAddressPayloadSchema from rpc), AddressSuggestion (matching response schema), and SuggestAddressError
• Import and re-export relevant types from @smart-address/core and @smart-address/rpc/suggest for consistency
• Define strategy type as 'fast' | 'reliable' union matching the RPC AddressStrategy type

Task 3: HTTP Client Implementation

Build the plain JavaScript HTTP client with native fetch and no framework dependencies.

• Create packages/sdk-core/src/client.ts with createSmartAddressClient(config) factory function that accepts { baseUrl, fetch?, headers? }
• Implement client.suggest(params) method that constructs HTTP GET/POST requests to /suggest endpoint, uses provided fetch implementation (defaulting to global fetch), handles JSON serialization/deserialization, and returns typed promise with suggestions array
• Ensure SSR-safe by avoiding direct window references and accepting custom fetch implementation
• Map SDK parameter names (text, limit, countryCode, etc.) directly to service payload fields

Task 4: TanStack Query Integration

Add caching layer using TanStack Query Core to prevent redundant API calls during typing.

• Create packages/sdk-core/src/query.ts with createSuggestAddressQuery(client, params) helper that returns TanStack Query configuration object with queryKey derived from params, queryFn calling client.suggest, and appropriate staleTime/cacheTime defaults (e.g., 30 seconds stale, 5 minutes cache)
• Export utility types for query results and options that framework packages can extend
• Implement proper request deduplication through query key generation (normalize params for consistent keys)

🤖 Prompt for AI agents

Build the core SDK foundation with HTTP client and caching layer.

Create packages/sdk-core with package.json and tsconfig.json
Set up rslib build configuration and ES2022 TypeScript target
Add TanStack Query Core dependency
Update root tsconfig with path alias for @smart-address/sdk-core

Create types.ts with SDK interfaces
Define SmartAddressConfig, SuggestAddressParams, AddressSuggestion,
SuggestAddressError types
Re-export types from @smart-address/core and @smart-address/rpc/suggest
Define strategy as 'fast' | 'reliable' union

Create client.ts with HTTP functionality
Implement createSmartAddressClient factory accepting baseUrl, fetch, and headers
Build client.suggest method for /suggest endpoint using fetch
Handle JSON serialization/deserialization
Ensure SSR-safe implementation

Create query.ts for caching
Implement createSuggestAddressQuery helper returning TanStack Query config
Generate normalized query keys from params
Set staleTime and cacheTime defaults
Export utility types for query results

Phase 2: React SDK Package

Create React-specific bindings with hooks and an optional autocomplete component.

Task 1: Package Setup

Set up packages/sdk-react with React peer dependencies and build configuration.

• Create packages/sdk-react/package.json with package name @smart-address/sdk-react, rslib build configuration, and peer dependencies on React 18+ and TanStack Query React
• Add @smart-address/sdk-core as a workspace dependency
• Configure subpath exports for hooks and optional component separately if needed
• Create packages/sdk-react/tsconfig.json extending root config with React types

Task 2: Core Hooks

Implement React hooks for accessing the SDK client and suggestions query.

• Create packages/sdk-react/src/useSmartAddress.ts with useSmartAddress(config) hook that creates and memoizes the SDK client using useMemo, returning client instance for direct imperative usage
• Create packages/sdk-react/src/useSuggestAddress.ts with useSuggestAddress(params, options?) hook that wraps TanStack Query's useQuery with the suggest query configuration from core package, returning query result with suggestions, loading state, and error
• Handle SSR scenarios by checking for fetch availability before creating client

Task 3: Autocomplete Component

Build a minimal autocomplete component with keyboard navigation and basic styling.

• Create packages/sdk-react/src/AddressAutocomplete.tsx component accepting props: strategy, countryCode, locale, sessionToken, limit, placeholder, onSelect, and styling props
• Implement combobox ARIA pattern with role="combobox", aria-expanded, aria-owns, aria-activedescendant for accessibility
• Handle keyboard navigation (ArrowUp/Down for selection, Enter for confirming, Escape for closing)
• Use useSuggestAddress hook internally with debouncing on input changes
• Render suggestions list with basic styling using Tailwind-compatible class names or CSS modules for easy customization
• Emit selected suggestion via onSelect callback

🤖 Prompt for AI agents

Build React SDK with hooks and autocomplete component.

Create packages/sdk-react with package.json and tsconfig.json
Set up peer dependencies for React 18+ and TanStack Query React
Add @smart-address/sdk-core workspace dependency
Configure rslib build and React types

Create useSmartAddress.ts hook
Implement useSmartAddress(config) using useMemo for client instance
Handle SSR by checking fetch availability

Create useSuggestAddress.ts hook
Wrap TanStack Query's useQuery with suggest query configuration
Return suggestions, loading state, and error

Create AddressAutocomplete.tsx component
Accept props for strategy, countryCode, locale, sessionToken, limit,
placeholder, onSelect, and styling
Implement ARIA combobox pattern with proper roles and attributes
Handle keyboard navigation for ArrowUp/Down, Enter, Escape
Use useSuggestAddress internally with input debouncing
Render suggestions list with Tailwind-compatible styling
Emit onSelect callback with selected suggestion

Phase 3: Vue SDK Package

Create Vue 3 composables and component using Composition API patterns.

Task 1: Package Setup

Set up packages/sdk-vue with Vue 3 peer dependencies.

• Create packages/sdk-vue/package.json with package name @smart-address/sdk-vue, peer dependencies on Vue 3.3+ and TanStack Query Vue (optional peer)
• Add @smart-address/sdk-core workspace dependency
• Configure build for Vue SFC and TypeScript support
• Create packages/sdk-vue/tsconfig.json extending root with Vue types

Task 2: Composables

Implement Vue composables mirroring React hook patterns.

• Create packages/sdk-vue/src/useSmartAddress.ts composable that creates SDK client using shallowRef for stable instance across re-renders
• Create packages/sdk-vue/src/useSuggestAddress.ts composable wrapping TanStack Query Vue's useQuery with suggest configuration, returning reactive query result
• Ensure composables work in both setup() context and script setup syntax

Task 3: Vue Autocomplete Component

Build Vue SFC autocomplete component with template-based rendering.

• Create packages/sdk-vue/src/AddressAutocomplete.vue accepting props matching React component API (strategy, countryCode, locale, etc.)
• Implement same ARIA combobox pattern and keyboard navigation as React version
• Use useSuggestAddress composable internally with watchDebounced for input changes
• Define select event for chosen suggestions
• Use scoped styles with CSS variables for theming

🤖 Prompt for AI agents

Build Vue SDK with composables and SFC component.

Create packages/sdk-vue with package.json and tsconfig.json
Set up peer dependencies for Vue 3.3+ and optional TanStack Query Vue
Add @smart-address/sdk-core workspace dependency
Configure build for Vue SFC and TypeScript

Create useSmartAddress.ts composable
Implement useSmartAddress using shallowRef for stable client instance
Ensure compatibility with setup() and script setup

Create useSuggestAddress.ts composable
Wrap TanStack Query Vue's useQuery with suggest configuration
Return reactive query result

Create AddressAutocomplete.vue SFC
Accept props matching React API (strategy, countryCode, locale, sessionToken,
limit, placeholder)
Implement ARIA combobox pattern with keyboard navigation
Use useSuggestAddress with watchDebounced for input changes
Define select event emitter
Add scoped styles with CSS variables for theming

Phase 4: Svelte SDK Package

Create Svelte stores and component using Svelte's reactive patterns.

Task 1: Package Setup

Set up packages/sdk-svelte with Svelte peer dependencies.

• Create packages/sdk-svelte/package.json with package name @smart-address/sdk-svelte, peer dependencies on Svelte 4+
• Add @smart-address/sdk-core workspace dependency
• Configure Svelte compiler and TypeScript support in build
• Create packages/sdk-svelte/tsconfig.json extending root with Svelte types

Task 2: Stores and Actions

Implement Svelte stores for client and suggestions state.

• Create packages/sdk-svelte/src/stores.ts with createSmartAddressStore(config) factory returning writable store containing SDK client instance
• Create packages/sdk-svelte/src/suggest.ts with createSuggestStore(client, params) that manages suggestion query state (loading, data, error) using Svelte's derived/writable stores
• Optionally provide a Svelte action (use:smartAddress) for attaching autocomplete behavior to input elements

Task 3: Svelte Autocomplete Component

Build Svelte component with reactive declarations.

• Create packages/sdk-svelte/src/AddressAutocomplete.svelte accepting props for configuration and binding selection
• Implement ARIA combobox pattern and keyboard navigation matching other frameworks
• Use createSuggestStore internally with reactive statements for debouncing
• Define select event dispatcher for suggestion selection
• Style with CSS variables for theming

🤖 Prompt for AI agents

Build Svelte SDK with stores and component.

Create packages/sdk-svelte with package.json and tsconfig.json
Set up peer dependencies for Svelte 4+
Add @smart-address/sdk-core workspace dependency
Configure Svelte compiler and TypeScript support

Create stores.ts with Svelte stores
Implement createSmartAddressStore factory returning writable store with client
instance

Create suggest.ts with query state management
Implement createSuggestStore managing loading, data, and error states
Optionally provide use:smartAddress action for input elements

Create AddressAutocomplete.svelte component
Accept props for configuration and selection binding
Implement ARIA combobox pattern with keyboard navigation
Use createSuggestStore internally with reactive debouncing
Define select event dispatcher
Style with CSS variables for theming

Phase 5: Web Component Package

Create framework-agnostic custom element for drop-in usage.

Task 1: Package Setup

Set up packages/web-component with native Web Components API.

• Create packages/web-component/package.json with package name @smart-address/web-component, no framework peer dependencies
• Add @smart-address/sdk-core workspace dependency
• Configure build to output ES module for modern browsers and optional UMD for legacy
• Create packages/web-component/tsconfig.json with DOM types

Task 2: Custom Element Implementation

Build the <smart-address-autocomplete> custom element with Shadow DOM.

• Create packages/web-component/src/index.ts defining custom element class extending HTMLElement
• Implement Shadow DOM with this.attachShadow({ mode: 'open' }) for style encapsulation
• Define observed attributes: base-url, strategy, limit, country-code, locale, session-token, placeholder
• Use attributeChangedCallback to react to attribute changes and re-initialize client/query
• Create internal structure: input element, suggestions dropdown container

Task 3: ARIA and Keyboard Navigation

Implement accessible combobox pattern in the custom element.

• Add ARIA attributes to input (role="combobox", aria-controls, aria-expanded, aria-autocomplete="list")
• Create suggestions list with role="listbox" and suggestion items with role="option"
• Handle keyboard events: ArrowDown/Up for navigation, Enter for selection, Escape for closing, Tab for focus management
• Manage focus and active descendant tracking for screen reader support

Task 4: Styling and Theming

Implement CSS custom properties for theming within Shadow DOM.

• Create packages/web-component/src/styles.css defining default styles with CSS variables: --smart-address-font-family, --smart-address-bg-color, --smart-address-text-color, --smart-address-border-radius, --smart-address-shadow, etc.
• Inject styles into Shadow DOM during component construction
• Document theming approach in component comments

Task 5: Events and Integration

Define custom events for integration with parent applications.

• Dispatch smartaddress:select CustomEvent when user selects suggestion, with detail containing full suggestion object
• Dispatch smartaddress:error CustomEvent on API errors or validation failures
• Implement value property getter/setter to allow programmatic access to current input
• Register custom element with customElements.define('smart-address-autocomplete', SmartAddressAutocomplete)

🤖 Prompt for AI agents

Build framework-agnostic Web Component with Shadow DOM.

Create packages/web-component with package.json and tsconfig.json
Add @smart-address/sdk-core workspace dependency
Configure build for ES module and optional UMD output
Add DOM types to TypeScript config

Create index.ts with custom element class
Extend HTMLElement for custom element
Implement Shadow DOM with attachShadow({ mode: 'open' })
Define observed attributes: base-url, strategy, limit, country-code, locale,
session-token, placeholder
Implement attributeChangedCallback for reactive updates
Create internal input and suggestions dropdown structure

Implement ARIA combobox pattern
Add ARIA attributes to input (role, aria-controls, aria-expanded,
aria-autocomplete)
Create suggestions list with role="listbox" and items with role="option"
Handle keyboard navigation for ArrowDown/Up, Enter, Escape, Tab
Manage focus and active descendant tracking

Create styles.css with theming
Define CSS variables for font-family, bg-color, text-color, border-radius,
shadow, etc.
Inject styles into Shadow DOM
Document theming approach

Implement custom events
Dispatch smartaddress:select with suggestion detail
Dispatch smartaddress:error for API errors
Implement value getter/setter property
Register element with customElements.define

Phase 6: Documentation and Examples

Create comprehensive documentation and integration guides for all SDK packages.

Task 1: SDK Reference Documentation

Add reference documentation to the existing Rspress docs structure.

• Create apps/docs/content/en/reference/sdk-core.md documenting core client API: createSmartAddressClient, client.suggest, configuration options, and TanStack Query integration
• Create apps/docs/content/en/reference/sdk-react.md documenting React hooks and component with TypeScript type signatures and prop definitions
• Create similar reference pages for Vue, Svelte, and Web Component in apps/docs/content/en/reference/
• Update apps/docs/content/en/reference/_meta.json to include navigation entries for all new SDK pages

Task 2: Integration Tutorials

Create practical how-to guides showing real-world integration.

• Create apps/docs/content/en/tutorials/sdk-quickstart.md with quick start examples for each framework showing minimal setup
• Create apps/docs/content/en/how-to/integrate-react.md with detailed React integration guide including form handling and validation patterns
• Create similar how-to guides for Vue and Svelte integration in apps/docs/content/en/how-to/
• Add Web Component integration guide showing vanilla JS and popular framework usage

Task 3: Code Examples

Create runnable example applications demonstrating SDK usage.

• Create example directories in each SDK package showing minimal integration (e.g., packages/sdk-react/examples/basic)
• Include examples showing strategy selection, session token usage, and custom styling
• Optionally create a demo app in apps/examples/ showcasing all SDK variants side-by-side

Task 4: API Migration Path

Document the relationship between SDK and existing integration patterns.

• Update apps/docs/content/en/explanation/architecture.md to explain SDK layer in the overall architecture
• Document how SDK relates to RPC client and when to use each
• Provide guidance on choosing between framework packages and web component

🤖 Prompt for AI agents

Create comprehensive documentation and examples for all SDK packages.

Create reference documentation in apps/docs/content/en/reference/
Document sdk-core.md with createSmartAddressClient, client.suggest, config
options, TanStack Query integration
Document sdk-react.md with hooks and component APIs, TypeScript signatures
Create reference pages for Vue, Svelte, and Web Component
Update _meta.json with navigation entries

Create integration tutorials
Add tutorials/sdk-quickstart.md with minimal setup for each framework
Create how-to/integrate-react.md with detailed React guide including forms and
validation
Add how-to guides for Vue and Svelte
Create Web Component integration guide for vanilla JS and frameworks

Create runnable code examples
Add example directories in each SDK package (e.g.,
packages/sdk-react/examples/basic)
Include examples for strategy selection, session tokens, custom styling
Optionally create apps/examples/ with side-by-side SDK variants demo

Document architecture and migration
Update explanation/architecture.md with SDK layer explanation
Document SDK vs RPC client usage guidance
Provide guidance on choosing framework packages vs web component

---

🚀 Next Steps

🤖 All AI agent prompts combined

Task: 1

Build the core SDK foundation with HTTP client and caching layer.

Create packages/sdk-core with package.json and tsconfig.json
Set up rslib build configuration and ES2022 TypeScript target
Add TanStack Query Core dependency
Update root tsconfig with path alias for @smart-address/sdk-core

Create types.ts with SDK interfaces
Define SmartAddressConfig, SuggestAddressParams, AddressSuggestion,
SuggestAddressError types
Re-export types from @smart-address/core and @smart-address/rpc/suggest
Define strategy as 'fast' | 'reliable' union

Create client.ts with HTTP functionality
Implement createSmartAddressClient factory accepting baseUrl, fetch, and headers
Build client.suggest method for /suggest endpoint using fetch
Handle JSON serialization/deserialization
Ensure SSR-safe implementation

Create query.ts for caching
Implement createSuggestAddressQuery helper returning TanStack Query config
Generate normalized query keys from params
Set staleTime and cacheTime defaults
Export utility types for query results
===============================================================================

Task: 2

Build React SDK with hooks and autocomplete component.

Create packages/sdk-react with package.json and tsconfig.json
Set up peer dependencies for React 18+ and TanStack Query React
Add @smart-address/sdk-core workspace dependency
Configure rslib build and React types

Create useSmartAddress.ts hook
Implement useSmartAddress(config) using useMemo for client instance
Handle SSR by checking fetch availability

Create useSuggestAddress.ts hook
Wrap TanStack Query's useQuery with suggest query configuration
Return suggestions, loading state, and error

Create AddressAutocomplete.tsx component
Accept props for strategy, countryCode, locale, sessionToken, limit,
placeholder, onSelect, and styling
Implement ARIA combobox pattern with proper roles and attributes
Handle keyboard navigation for ArrowUp/Down, Enter, Escape
Use useSuggestAddress internally with input debouncing
Render suggestions list with Tailwind-compatible styling
Emit onSelect callback with selected suggestion
===============================================================================

Task: 3

Build Vue SDK with composables and SFC component.

Create packages/sdk-vue with package.json and tsconfig.json
Set up peer dependencies for Vue 3.3+ and optional TanStack Query Vue
Add @smart-address/sdk-core workspace dependency
Configure build for Vue SFC and TypeScript

Create useSmartAddress.ts composable
Implement useSmartAddress using shallowRef for stable client instance
Ensure compatibility with setup() and script setup

Create useSuggestAddress.ts composable
Wrap TanStack Query Vue's useQuery with suggest configuration
Return reactive query result

Create AddressAutocomplete.vue SFC
Accept props matching React API (strategy, countryCode, locale, sessionToken,
limit, placeholder)
Implement ARIA combobox pattern with keyboard navigation
Use useSuggestAddress with watchDebounced for input changes
Define select event emitter
Add scoped styles with CSS variables for theming
===============================================================================

Task: 4

Build Svelte SDK with stores and component.

Create packages/sdk-svelte with package.json and tsconfig.json
Set up peer dependencies for Svelte 4+
Add @smart-address/sdk-core workspace dependency
Configure Svelte compiler and TypeScript support

Create stores.ts with Svelte stores
Implement createSmartAddressStore factory returning writable store with client
instance

Create suggest.ts with query state management
Implement createSuggestStore managing loading, data, and error states
Optionally provide use:smartAddress action for input elements

Create AddressAutocomplete.svelte component
Accept props for configuration and selection binding
Implement ARIA combobox pattern with keyboard navigation
Use createSuggestStore internally with reactive debouncing
Define select event dispatcher
Style with CSS variables for theming
===============================================================================

Task: 5

Build framework-agnostic Web Component with Shadow DOM.

Create packages/web-component with package.json and tsconfig.json
Add @smart-address/sdk-core workspace dependency
Configure build for ES module and optional UMD output
Add DOM types to TypeScript config

Create index.ts with custom element class
Extend HTMLElement for custom element
Implement Shadow DOM with attachShadow({ mode: 'open' })
Define observed attributes: base-url, strategy, limit, country-code, locale,
session-token, placeholder
Implement attributeChangedCallback for reactive updates
Create internal input and suggestions dropdown structure

Implement ARIA combobox pattern
Add ARIA attributes to input (role, aria-controls, aria-expanded,
aria-autocomplete)
Create suggestions list with role="listbox" and items with role="option"
Handle keyboard navigation for ArrowDown/Up, Enter, Escape, Tab
Manage focus and active descendant tracking

Create styles.css with theming
Define CSS variables for font-family, bg-color, text-color, border-radius,
shadow, etc.
Inject styles into Shadow DOM
Document theming approach

Implement custom events
Dispatch smartaddress:select with suggestion detail
Dispatch smartaddress:error for API errors
Implement value getter/setter property
Register element with customElements.define
===============================================================================

Task: 6

Create comprehensive documentation and examples for all SDK packages.

Create reference documentation in apps/docs/content/en/reference/
Document sdk-core.md with createSmartAddressClient, client.suggest, config
options, TanStack Query integration
Document sdk-react.md with hooks and component APIs, TypeScript signatures
Create reference pages for Vue, Svelte, and Web Component
Update _meta.json with navigation entries

Create integration tutorials
Add tutorials/sdk-quickstart.md with minimal setup for each framework
Create how-to/integrate-react.md with detailed React guide including forms and
validation
Add how-to guides for Vue and Svelte
Create Web Component integration guide for vanilla JS and frameworks

Create runnable code examples
Add example directories in each SDK package (e.g.,
packages/sdk-react/examples/basic)
Include examples for strategy selection, session tokens, custom styling
Optionally create apps/examples/ with side-by-side SDK variants demo

Document architecture and migration
Update explanation/architecture.md with SDK layer explanation
Document SDK vs RPC client usage guidance
Provide guidance on choosing framework packages vs web component

💡 Iterate on the plan with: @coderabbitai <feedback>

Example Feedback
- @coderabbitai You can skip phase 3. Add a simple unit test case for phase 2.
- @coderabbitai For assumption 1 go ahead with option 3 and replan.

---

💬 Have feedback or questions? Drop into our discord!