@orderlyshop/web-components 0.1.0-build.7045

package/docs/components/README.md

@@ -0,0 +1,708 @@
+# 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, responsive full-width tracks, capped tile widths, 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. The default hero stretches across the available page width and centers its intro content.
+
+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`.
+
+In vertical mode, or when the horizontal menu falls back to its mobile drawer, items with children expand on first click and navigate/select on the next click. In horizontal desktop mode, top-level and second-level links navigate/select on click when they have an `href`, while dedicated toggles control which branch or dropdown is open.
+
+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`.
+
+Set `layout="horizontal"` to render a desktop navigation bar in the same pattern as `orderly.shop`: choose a top-level item, render the next level as a separate horizontal row, and show the third level as a dropdown from the active second-level item. The top row stays on one line and scrolls horizontally when it overflows instead of wrapping. The second row spans the full available navigation width, including the separator line above it. On narrow viewports the component automatically falls back to the existing drawer-style mobile navigation, so the horizontal option does not require a separate mobile implementation.
+
+In horizontal mode, the active or expanded top-level and second-level categories also render a dedicated indicator line. By default it tracks the text width inside the link padding, and it remains purely presentational and themeable through CSS custom properties.
+
+Attributes:
+
+- `layout`: `vertical` (default) or `horizontal`
+- `sticky`
+
+Properties:
+
+- `items`
+- `controller`
+- `layout`
+- `sticky`
+
+Events:
+
+- `orderly-navigation-select`
+
+Slots:
+
+- `before-items`: inline content before the navigation items. Useful for logos or compact utility content.
+- `after-items`: inline content after the navigation items. Useful for marketing copy, badges, or CTA blocks.
+
+Templates:
+
+- `navigation`
+- `item`
+
+Styling hooks:
+
+- Data attributes:
+  - `[data-orderly-layout="horizontal"]`
+  - `[data-orderly-level="0"]`, `[data-orderly-level="1"]`, ...
+  - `[data-orderly-has-children]`
+  - `[data-orderly-active]`
+  - `[data-orderly-expanded]`
+- CSS custom properties:
+  - `--orderly-navigation-horizontal-padding`
+  - `--orderly-navigation-horizontal-inline-padding`
+  - `--orderly-navigation-link-padding`
+  - `--orderly-navigation-link-padding-horizontal`
+  - `--orderly-navigation-link-radius`
+  - `--orderly-navigation-link-background`
+  - `--orderly-navigation-link-color`
+  - `--orderly-navigation-link-hover-background`
+  - `--orderly-navigation-link-hover-color`
+  - `--orderly-navigation-link-active-background`
+  - `--orderly-navigation-link-active-color`
+  - `--orderly-navigation-indicator-color`
+  - `--orderly-navigation-indicator-height`
+  - `--orderly-navigation-indicator-radius`
+  - `--orderly-navigation-indicator-inset`
+  - `--orderly-navigation-indicator-start-offset`
+  - `--orderly-navigation-indicator-end-offset`
+  - `--orderly-navigation-indicator-offset`
+  - `--orderly-navigation-indicator-collapsed-scale`
+  - `--orderly-navigation-child-link-color`
+  - `--orderly-navigation-child-link-font-size`
+  - `--orderly-navigation-child-link-font-weight`
+  - `--orderly-navigation-subnav-padding`
+  - `--orderly-navigation-subnav-border-top`
+  - `--orderly-navigation-subnav-link-padding`
+  - `--orderly-navigation-dropdown-offset`
+  - `--orderly-navigation-dropdown-min-width`
+  - `--orderly-navigation-dropdown-max-width`
+  - `--orderly-navigation-dropdown-border`
+  - `--orderly-navigation-dropdown-radius`
+  - `--orderly-navigation-dropdown-background`
+  - `--orderly-navigation-dropdown-shadow`
+  - `--orderly-navigation-megamenu-border`
+  - `--orderly-navigation-megamenu-radius`
+  - `--orderly-navigation-megamenu-background`
+  - `--orderly-navigation-megamenu-shadow`
+
+Example:
+
+```html
+<orderly-navigation
+  layout="horizontal"
+  aria-label="Main navigation"
+></orderly-navigation>
+```
+
+Inline custom content:
+
+```html
+<orderly-navigation layout="horizontal" aria-label="Main navigation">
+  <a slot="before-items" href="/" class="shop-nav__logo">
+    <img src="/brand/logo.svg" alt="Orderly" />
+  </a>
+
+  <aside slot="after-items" class="shop-nav__promo">
+    Fri fragt over 499 kr.
+  </aside>
+</orderly-navigation>
+```
+
+Custom item template:
+
+```html
+<orderly-navigation layout="horizontal" aria-label="Main navigation">
+  <template data-orderly-template="item">
+    <li class="shop-nav__item" data-orderly-item>
+      <a class="shop-nav__link" data-orderly-action="select">
+        <span data-orderly-bind="label"></span>
+      </a>
+      <button class="shop-nav__toggle" type="button" data-orderly-action="toggle">
+        More
+      </button>
+      <div class="shop-nav__children" data-orderly-slot="children"></div>
+    </li>
+  </template>
+</orderly-navigation>
+```
+
+### 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 opens a full-page overlay, immediately renders product results below the search field, and then searches automatically after the debounce delay as the user types. When no search text has been entered yet, the overlay defaults to the target grid's current sort order or the shop's default "latest products" sort. 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`