@orderlyshop/web-components 0.1.0

package/docs/components/README.md

@@ -0,0 +1,610 @@
+# Component API Reference
+
+This reference is optimized for developers and agents using `@orderlyshop/web-components` in vanilla HTML, JavaScript, and TypeScript projects.
+
+Machine-readable metadata is also shipped:
+
+- `custom-elements.json` for custom element tooling and agents.
+- `html-custom-data.json` for VS Code HTML autocomplete.
+
+## Common Conventions
+
+- Core contracts such as `SearchQuery`, `SearchObject`, `DraftOrder`, and `OrderlyClient` are assigned as JavaScript properties.
+- Primitive configuration is exposed as attributes.
+- Default rendering uses light DOM and stable `orderly-*` classes.
+- `defineOrderlyWebComponents()` installs package-owned baseline CSS, so default components have usable spacing, layout, responsive behavior, and product presentation without a shop stylesheet.
+- Override the default look with normal CSS targeting `orderly-*` classes or variables such as `--orderly-color-accent`, `--orderly-color-page`, and `--orderly-content-max-width`.
+- Templates use `data-orderly-template`, `data-orderly-bind`, `data-orderly-slot`, and `data-orderly-action`.
+- Shared document-level templates can use `data-orderly-for="product-tile"` or another component name so one shop template registry can serve every page.
+- Responsive templates can use `data-orderly-viewport="mobile"`, `data-orderly-viewport="desktop"`, or `data-orderly-media`.
+- `base-url` configures the backend when no `client` property is supplied.
+- Built-in labels and messages are Danish by default. Set `configureShop({ uiLanguage: "EN" })` for English defaults; explicit attributes, typed properties, and templates still override those strings.
+
+## Declarative Query Format
+
+`orderly-product-grid`, `orderly-product-rail`, and `orderly-collection-page` support simple declarative search query markup.
+
+Attributes:
+
+- `keywords`: maps to `SearchQuery.Query`.
+- `tags`: comma-separated values mapped to `SearchQuery.Tags`.
+- `hidden-query`: maps to `SearchQuery.HiddenQuery`.
+- `order-by`: comma-separated values mapped to `SearchQuery.OrderBy`.
+- `store-id`: maps to `SearchQuery.StoreId`.
+- `featured`: boolean mapped to `SearchQuery.Featured`.
+
+Example:
+
+```html
+<orderly-product-rail
+  title="Børnetøj"
+  keywords="H&M"
+  tags="børnetøj,bluser"
+  order-by="CreatedTime desc">
+</orderly-product-rail>
+```
+
+Equivalent child markup:
+
+```html
+<orderly-product-rail title="Børnetøj">
+  <query>
+    <tags>børnetøj,bluser</tags>
+    <keywords>H&M</keywords>
+    <order-by>CreatedTime desc</order-by>
+  </query>
+</orderly-product-rail>
+```
+
+For the full Core query contract, assign the typed `query` property from JavaScript.
+Vanilla browser scripts that use the standalone bundle can create typed queries with `OrderlyWebComponents.createSearchQuery({ query, tags, orderBy })`; module-based shops can import the same helper from `@orderlyshop/web-components/query`.
+
+## Global Template Registry
+
+Local templates placed inside an element take precedence. If no local template matches, components look for global templates in the document and in the JavaScript registry.
+
+```html
+<template data-orderly-template="product" data-orderly-for="product-tile">
+  <article class="product-card">
+    <h3 data-orderly-bind="title"></h3>
+    <orderly-stored-image data-orderly-bind="image" fit="contain"></orderly-stored-image>
+    <button type="button" data-orderly-action="add-to-basket">
+      <span data-orderly-bind="basket-action-icon"></span>
+    </button>
+  </article>
+</template>
+```
+
+Use `data-orderly-for` with a full custom element name, a prefix-independent component name such as `product-tile`, or `*`. Global templates support `data-orderly-viewport` and `data-orderly-media`.
+
+## Components
+
+### `orderly-page-layout`
+
+Reusable page structure with slots for `utility`, `header`, `header-actions`, `primary-nav`, `left`, `right`, `content-before`, `content`, `content-after`, `footer`, and `overlay`.
+
+Attributes:
+
+- `logo-src`
+- `logo-alt`
+- `logo-href`
+
+Templates:
+
+- `layout`
+
+### `orderly-category-page`
+
+Default shop category page that composes layout, navigation, search, collection, product grid, basket, product detail, and footer.
+
+Attributes:
+
+- `base-url`
+- `slug`
+- `brand-label`
+- `product-href`
+- `checkout-href`
+- `checkout-label`
+- `search-placeholder`
+- `empty-label`
+
+Properties:
+
+- `client`
+- `defaultQuery`
+- `query` through child grid/collection composition
+- `category`
+- `navigationItems`
+- `sortOptions`
+- `basketController`
+
+Templates:
+
+- `layout`
+- `empty-category`
+
+`orderly-category-page` can resolve its category from generated path URLs by default, from `slug`, or from a static hash route when a shop opts into hash routing:
+
+```html
+<a href="/categories/sko/">Sko</a>
+<orderly-category-page></orderly-category-page>
+
+<orderly-category-page slug="sko"></orderly-category-page>
+```
+
+`navigationDefinitions` must define an explicit unique `slug` on every item. If the configured navigation is invalid, the component renders a visible category configuration error instead of silently falling back to another category.
+
+When a product is opened in the default product detail popup, the popup includes an icon link to the full product page. It uses `product-href`, defaulting to `/product.html`, and appends the Core `SearchObject.ShareURL.URL` as `#url=...`. For `https://orderly.shop/...` product URLs, the hash value is compacted to the path before encoding.
+
+### `orderly-home-page`
+
+Default storefront homepage that renders one horizontal `orderly-product-rail` for every configured top-level category. It also composes page layout, side navigation, basket icon, basket drawer, product detail dialog, and footer.
+
+Attributes:
+
+- `base-url`
+- `brand-label`
+- `eyebrow`
+- `title`
+- `rail-cta-label`
+- `empty-label`
+- `product-href`
+- `checkout-href`
+- `checkout-label`
+
+Properties:
+
+- `client`
+- `defaultQuery`
+- `navigationItems`
+- `sortOptions`
+- `basketController`
+- `basketLabels`
+
+Slots:
+
+- `utility`
+- `header-actions`
+- `content-before`
+- `content-after`
+- `footer`
+- `overlay`
+
+Templates:
+
+- `layout`
+- `rail`
+- `grid`
+- `product`
+- `loading`
+- `empty`
+
+### `orderly-checkout-page`
+
+Default checkout page that composes page layout, side navigation, checkout form, basket order summary, footer, and shared basket state.
+
+Attributes:
+
+- `base-url`
+- `brand-label`
+- `title`
+- `description`
+- `order-title`
+- `terms-href`
+
+Properties:
+
+- `client`
+- `basketController`
+- `navigationItems`
+- `basketLabels`
+- `checkoutLabels`
+
+Slots:
+
+- `utility`
+- `header-actions`
+- `content-before`
+- `content-after`
+- `footer`
+- `overlay`
+
+Templates:
+
+- `layout`
+- `checkout`
+- `basket`
+- `line`
+- `empty`
+
+### `orderly-product-detail-page`
+
+Default product detail page that composes page layout, navigation, product detail, basket drawer, and footer. It resolves the `SearchObject` itself by calling `SearchService.Search` with `SearchQuery.ShareUrl`.
+
+```html
+<orderly-product-detail-page share-url="https://shop.example/products/my-product"></orderly-product-detail-page>
+```
+
+For static product routes, omit `share-url` and pass the encoded product share URL in the page hash:
+
+```html
+<a href="/product.html#url=https%3A%2F%2Fshop.example%2Fproducts%2Fmy-product">View product</a>
+<orderly-product-detail-page></orderly-product-detail-page>
+```
+
+Orderly product URLs can use the compact form. The component restores `https://orderly.shop/` before searching:
+
+```html
+<a href="/product.html#url=mickey-mouse-billedramme-fra-danish-design-str-40x50-cm-p7yxrjsfbq.html">Se produkt</a>
+<orderly-product-detail-page></orderly-product-detail-page>
+```
+
+Attributes:
+
+- `base-url`
+- `share-url`
+- `brand-label`
+- `checkout-href`
+- `checkout-label`
+- `add-label`
+- `loading-label`
+- `not-found-label`
+- `error-label`
+
+Properties:
+
+- `client`
+- `shareUrl`
+- `product`
+- `defaultQuery`
+- `navigationItems`
+- `basketController`
+- `basketLabels`
+
+Events:
+
+- `orderly-product-loaded`
+- `orderly-product-not-found`
+- `orderly-error`
+
+Templates:
+
+- `layout`
+- `product`
+- `thumbnail`
+- `basket`
+- `line`
+- `empty`
+
+### `orderly-product-grid`
+
+Search-backed product listing with sort controls, continuation-token paging, loading states, and template overrides.
+
+Detailed reference: [product-grid.md](./product-grid.md)
+
+### `orderly-product-rail`
+
+Horizontal product rail for homepages and editorial rows. It composes `orderly-product-grid`.
+
+Detailed reference: [product-rail.md](./product-rail.md)
+
+### `orderly-collection-page`
+
+Collection hero plus product grid.
+
+Attributes:
+
+- `base-url`
+- `title`
+- `description`
+- `hero-image`
+- `cta-label`
+- `cta-href`
+- Declarative query attributes: `keywords`, `tags`, `hidden-query`, `order-by`, `store-id`, `featured`
+
+Properties:
+
+- `client`
+- `query`
+- `defaultQuery`
+- `basketController`
+- `sortOptions`
+
+Templates:
+
+- `layout`
+- `hero`
+- `grid`
+- `product`
+- `loading`
+- `empty`
+
+### `orderly-product-tile`
+
+Product card for `SearchObject`.
+
+Default product cards include `schema.org/Product` and `schema.org/Offer` microdata for Google product snippets. Custom templates should preserve the `data-orderly-bind="schema-*"` placeholders when they replace the default product card markup.
+
+Attributes:
+
+- `add-label`
+- `remove-label`
+
+Properties:
+
+- `product`
+- `basketController`
+
+Events:
+
+- `orderly-product-selected`
+- `orderly-add-to-basket`
+- `orderly-remove-from-basket`
+
+Templates:
+
+- `product`
+- `default`
+
+### `orderly-product-page`
+
+Product detail view with thumbnail gallery and add-to-basket action.
+
+Attributes:
+
+- `add-label`
+
+Properties:
+
+- `product`
+- `selectedImageIndex`
+- `basketController`
+
+Events:
+
+- `orderly-add-to-basket`
+- `orderly-product-image-selected`
+
+Templates:
+
+- `product`
+- `thumbnail`
+
+### `orderly-credit`
+
+Formats and renders a Core `Credit` value as stylable money markup. DKK values are formatted as `kr. <pris>`, for example `kr. 100,00`.
+
+```html
+<orderly-credit amount="100" currency="DKK"></orderly-credit>
+```
+
+Properties:
+
+- `credit`
+- `amount`
+- `currency`
+- `locale`
+- `emptyLabel`
+
+Attributes:
+
+- `amount`
+- `currency`
+- `locale`
+- `empty-label`
+
+Templates:
+
+- `credit`
+- `default`
+
+### `orderly-stored-image`
+
+Renders `StoredImage` with configured URL prefix, rotation, crop, and fit handling.
+
+Attributes:
+
+- `fit`
+- `variant`
+- `alt`
+
+Properties:
+
+- `image`
+
+Templates:
+
+- `image`
+
+### `orderly-basket-icon`
+
+Basket button with item count badge.
+
+Attributes:
+
+- `label`
+
+Properties:
+
+- `basketController`
+
+Events:
+
+- `orderly-basket-open`
+- `orderly-basket-change`
+
+Both events use the current `DraftOrder` as `event.detail`. Derive item count from `event.detail.OrderLines` instead of relying on a separate basket data shape.
+
+Templates:
+
+- `basket-icon`
+- `icon`
+
+### `orderly-basket`
+
+Basket overview backed by `DraftOrder`.
+
+Attributes:
+
+- `base-url`
+- `empty-label`
+- `clear-label`
+- `continue-label`
+- `continue-href`
+- `quantity-label`
+- `remove-label`
+- `subtotal-label`
+- `shipping-label`
+- `total-label`
+- `total-note`
+- `delivery-note`
+- `checkout-href`
+- `checkout-label`
+- `checkout-action`
+
+Properties:
+
+- `client`
+- `basketController`
+
+Events:
+
+- `orderly-basket-change`
+- `orderly-basket-verified`
+
+Both events use the current `DraftOrder` as `event.detail`. Basket components do not expose a duplicated internal basket data type.
+
+Templates:
+
+- `basket`
+- `line`
+- `empty`
+
+### `orderly-checkout`
+
+Checkout form for contact/address, delivery methods, service points, draft verification, and order creation.
+
+The default checkout layout hides the address country field and uses `DK` as the default `Address.CountryCodeIso2Letter`. When a Danish 4-digit postal code is entered, the component looks up the city name through Dataforsyningen's `https://api.dataforsyningen.dk/postnumre/{postnr}` endpoint and fills the city field if it is empty or was previously auto-filled.
+
+The default delivery UI follows the Orderly storefront pattern:
+
+- address fields are filled before delivery methods are shown
+- delivery methods render as selectable radio cards
+- service points render as a separate radio-card list when the selected delivery method requires a pickup point
+- selecting a delivery method or service point verifies the draft so basket totals can update immediately
+
+Attributes:
+
+- `base-url`
+- `terms-href`
+- `delivery-address-prompt-label`
+- `no-delivery-methods-label`
+- `service-point-help-label`
+- `no-service-points-label`
+
+Properties:
+
+- `client`
+- `basketController`
+- `profileStore`
+- `labels`
+
+Events:
+
+- `orderly-checkout-ready`
+- `orderly-checkout-delivery-selected`
+- `orderly-order-created`
+- `orderly-error`
+
+Templates:
+
+- `checkout`
+
+Default template slots:
+
+- `deliveryMethods`
+- `servicePoints`
+
+### `orderly-navigation`
+
+Navigation menu backed by `NavigationController`.
+
+For items with children, the item link expands the branch on first click when it is closed. A second click on the expanded item navigates/selects it. Items without children navigate/select on the first click.
+
+Navigation is sticky by default so side navigation remains visible while category/product content scrolls. Set `sticky="false"` to opt out. The same attribute works when navigation is slotted into `left`, `right`, or `primary-nav`.
+
+Attributes:
+
+- `sticky`
+
+Properties:
+
+- `items`
+- `controller`
+- `sticky`
+
+Events:
+
+- `orderly-navigation-select`
+
+Templates:
+
+- `navigation`
+- `item`
+
+### Search Controls
+
+Search controls bind to a target `orderly-product-grid`.
+
+Components:
+
+- `orderly-search-box`
+- `orderly-sort-select`
+- `orderly-filter-panel`
+- `orderly-load-more`
+
+Common attributes:
+
+- `for`
+- `mode`: `textbox` (default) or `icon`. Icon mode renders a search icon and opens a full-page overlay with a search input.
+- `placeholder`
+- `label`
+- `close-label`
+- `prompt-label`
+- `loading-label`
+- `error-label`
+- `empty-label`
+- `debounce-ms`: debounce delay for automatic search. Defaults to `500`.
+
+Icon mode searches automatically after the debounce delay and renders product results below the search field using `orderly-product-grid` and `orderly-product-tile`. It reuses the target grid's product, loading, and empty templates when available.
+
+Templates:
+
+- `search-box`
+- `sort-select`
+- `filter-panel`
+- `load-more`
+
+### `orderly-shop-footer`
+
+Configurable shop footer with logo, about text, address, contact information, opening hours, and information links.
+
+For shop-owned footer content, prefer a global template in shared HTML:
+
+```html
+<template data-orderly-template="footer" data-orderly-for="shop-footer">
+  <div class="orderly-shop-footer">
+    <p class="orderly-shop-footer__about">Independent shop copy.</p>
+  </div>
+</template>
+```
+
+The programmatic `configureShopFooter()` API remains available when a shop needs to build footer data from JavaScript.
+
+Templates:
+
+- `footer`
+- `address-line`
+- `contact-item`
+- `opening-hour`
+- `information-link`