# Theme SDK (/themes/sdk)

`@poltura/theme-sdk` is the public contract between a Poltura theme and the storefront that runs it: typed modules for authoring elements, reading store data and drawing every commerce feature.

## Importing [#importing]

Every name is imported from its module, `@poltura/theme-sdk/<module>`. There is no root import and no deep import, and no name is exported from two modules, so auto-import always picks the right one.

```tsx
import { defineSection, field } from '@poltura/theme-sdk/elements';
import { useCart } from '@poltura/theme-sdk/cart';
```

The package holds declarations only. The storefront provides the implementation at runtime, so a theme never bundles SDK code.

## Kinds of export [#kinds-of-export]

| Kind     | Name shape                             | What it is                                                                                                               |
| -------- | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| Hook     | `useX`                                 | State and actions. The logic runs on the host and returns declared types only.                                           |
| Part     | `<Feature><Piece>`, such as `CartLine` | Markup only, styled by tokens, `className` and `classes`. Parts never fetch data.                                        |
| Default  | `<Feature>`, such as `VariantPicker`   | The complete feature, built from its parts and hook. The storefront draws it when a theme ships nothing for the feature. |
| Definer  | `defineX`                              | Authoring calls the theme build reads statically.                                                                        |
| Function | camelCase verb                         | A pure helper without React. Rare.                                                                                       |
| Constant | camelCase object or `UPPER_CASE` value | Catalogue values, so themes never write magic strings.                                                                   |
| Type     | PascalCase                             | Declared in the package and documented property by property.                                                             |

Every feature follows the same pattern: a headless hook, parts that draw it and, for component-level features, a complete default. A theme can use the default, restyle it, or rebuild the feature from the hook and the parts.

## One way to do each thing [#one-way-to-do-each-thing]

- **Settings** arrive already coerced and translated: element settings as the typed `settings` prop, theme settings from `useThemeSettings()`, child blocks from `useChildBlocks()`.
- **Prices** are drawn by the `price` parts from a `PriceView`. Any other amount goes through `useFormat().money()`.
- **Data** comes from named domain hooks that take one object parameter and return one result shape.

## Versions [#versions]

This is theme API v1, and the package major is the theme API version: SDK `1.x` is theme API v1. A minor release adds exports or optional fields; only a new theme API version, released as SDK 2.0.0, removes or changes one. A theme written against one version keeps working on every later minor release of the same major.

## Modules [#modules]

| Module | Import | Purpose |
| --- | --- | --- |
| [elements](/themes/sdk/reference/elements) | `@poltura/theme-sdk/elements` | Authoring: define and override sections and blocks, fields, slots, inline editing and child blocks. |
| [layout](/themes/sdk/reference/layout) | `@poltura/theme-sdk/layout` | Layout primitives and section chrome: containers, stacks, rows, grids and section frames. |
| [sections](/themes/sdk/reference/sections) | `@poltura/theme-sdk/sections` | Complete defaults of the platform's section types, for a theme override to wrap or delegate to. |
| [settings](/themes/sdk/reference/settings) | `@poltura/theme-sdk/settings` | Theme settings and the settings of a template's own section. |
| [i18n](/themes/sdk/reference/i18n) | `@poltura/theme-sdk/i18n` | Translations, theme texts, the store's languages and the one formatter. |
| [store](/themes/sdk/reference/store) | `@poltura/theme-sdk/store` | The store: identity, contact, company, brand, social links, market and features. |
| [data](/themes/sdk/reference/data) | `@poltura/theme-sdk/data` | Store reads: products, categories, collections, attributes, product types and the content pages and posts a setting points to, each one named hook with one result shape. |
| [product](/themes/sdk/reference/product) | `@poltura/theme-sdk/product` | Products, variants, options, availability, specifications, reviews, the product page view and the buy box. |
| [price](/themes/sdk/reference/price) | `@poltura/theme-sdk/price` | Money, prices and price access: what a visitor may see and on which tax basis. |
| [listing](/themes/sdk/reference/listing) | `@poltura/theme-sdk/listing` | Collection, category and search listings: product cards, filters, sort and paging. |
| [cart](/themes/sdk/reference/cart) | `@poltura/theme-sdk/cart` | The cart: its lines, totals, codes and gift cards, the state and actions the cart hook returns, and the cart page's parts. |
| [checkout](/themes/sdk/reference/checkout) | `@poltura/theme-sdk/checkout` | Checkout parts a theme may place outside checkout, such as the accepted payment methods. |
| [customer](/themes/sdk/reference/customer) | `@poltura/theme-sdk/customer` | The signed-in shopper: customer, addresses, orders, the account area and the sign-in forms. |
| [search](/themes/sdk/reference/search) | `@poltura/theme-sdk/search` | Storefront search: the query, live results, suggestions and featured products. |
| [chrome](/themes/sdk/reference/chrome) | `@poltura/theme-sdk/chrome` | The header, footer and promo bar and their pieces: brand, user menu, switchers, mobile menu and colour mode. |
| [navigation](/themes/sdk/reference/navigation) | `@poltura/theme-sdk/navigation` | Store menus, the category and page tree, mega menu panels and breadcrumb trails. |
| [routing](/themes/sdk/reference/routing) | `@poltura/theme-sdk/routing` | Links, the router, page params and the merchant's site pages. |
| [media](/themes/sdk/reference/media) | `@poltura/theme-sdk/media` | Images, videos, placeholders, media library files and theme assets. |
| [forms](/themes/sdk/reference/forms) | `@poltura/theme-sdk/forms` | Store forms: the merchant's published forms, the newsletter sign-up and the contact form. |
| [content](/themes/sdk/reference/content) | `@poltura/theme-sdk/content` | Merchant content: blog posts, legal documents, the FAQ, guides, rich text, Markdown and the contact page. |
| [consent](/themes/sdk/reference/consent) | `@poltura/theme-sdk/consent` | Cookie consent: the shopper's choice and the actions that record it. |
| [inbox](/themes/sdk/reference/inbox) | `@poltura/theme-sdk/inbox` | The store's live chat: its state and actions, the complete widget and the parts it is built from. |
| [slots](/themes/sdk/reference/slots) | `@poltura/theme-sdk/slots` | App slots, app zones and host widget names. |
| [ui](/themes/sdk/reference/ui) | `@poltura/theme-sdk/ui` | Generic interface primitives, class merging and DOM hooks. |
| [editor](/themes/sdk/reference/editor) | `@poltura/theme-sdk/editor` | The customizer canvas: whether the page is being edited, and preview scenarios. |