@orderlyshop/web-components 0.1.0

package/README.md

@@ -0,0 +1,685 @@
+# `@orderlyshop/web-components`
+
+Headless native web components for Orderly storefronts.
+
+The package depends on `@orderlyshop/core-client` and wraps Core contracts such as `SearchObject`, `SearchQuery`, and `DraftOrder` in reusable browser components. Components render practical light-DOM defaults and expose typed properties, events, controllers, stores, and template overrides so host shops keep full control over CSS, layout, routing, and copy.
+
+## Install
+
+```sh
+npm install @orderlyshop/core-client @orderlyshop/web-components
+```
+
+## Create A Shop
+
+For a new vanilla storefront, run the scaffold command from the shop project:
+
+```sh
+npx orderly-init-shop
+npm install
+npm run dev
+```
+
+Agents and developers should use `npx orderly-init-shop` before hand-writing shop files. It creates `src/index.html`, `src/category.html`, `src/product.html`, `src/checkout.html`, `src/includes/head.html`, `src/navigation.ts`, `src/shop-query.ts`, `src/templates/*.html`, `src/style.css`, `vite.config.mjs`, and package scripts. Pass an account id when the shop-wide default query should be tenant-scoped from the start:
+
+```sh
+npx orderly-init-shop --account-id 00000000-0000-0000-0000-000000000000
+```
+
+The scaffold uses Vite for local development and static builds, but Vite is added to the generated shop's `devDependencies`. Local development is configured for `http://localhost:61677` because that is the backend CORS development origin. `@orderlyshop/web-components` does not depend on Vite at runtime.
+
+## Browser Standalone Bundle
+
+The package build also emits browser-ready standalone bundles with `@orderlyshop/core-client`, Connect, and protobuf runtime code included. These files are shipped in the npm package and are what the `unpkg` and `jsdelivr` package fields point at.
+
+Use the configurable bundle when a vanilla HTML site needs to set shop options before registering elements:
+
+```html
+<script src="/node_modules/@orderlyshop/web-components/dist/browser/orderly-web-components.global.js"></script>
+<script>
+  const { configureShop } = OrderlyWebComponents;
+
+  configureShop({
+    uiLanguage: "DA",
+    defaultShop: {
+      baseUrl: "https://service.orderly.shop",
+      navigationDefinitions: [
+        {
+          label: "Sko",
+          slug: "sko",
+          query: { query: "sko sneakers" },
+          children: [
+            { label: "Dame sko", slug: "dame-sko", query: { query: "dame sko sneakers" } }
+          ]
+        }
+      ]
+    }
+  });
+</script>
+```
+
+Use the auto-register bundle for the built-in default shop or pages that configure everything declaratively:
+
+```html
+<script src="/node_modules/@orderlyshop/web-components/dist/browser/orderly-web-components.define.global.js"></script>
+```
+
+The normal package entrypoints remain ESM for bundlers. The standalone files are classic browser scripts and expose `window.OrderlyWebComponents`.
+
+`configureShop()` is the recommended one-call setup for HTML head scripts. Its parameter is strongly typed as `ShopConfig`, so VS Code/TypeScript can provide completions directly on the object literal. All fields are optional: `uiLanguage`, `defaultShop`, `pageLayout`, `responsiveTemplates`, `shopFooter`, `storedImageUrls`, and `components`. It applies configuration first and then registers custom elements. Pass `components: false` only when elements are registered elsewhere.
+
+Built-in component copy is Danish by default (`uiLanguage: "DA"`). Set `uiLanguage: "EN"` to switch built-in labels, empty states, checkout copy, navigation controls, and page defaults to English. Shop-specific attributes, templates, and `defaultShop` label fields still take precedence over language defaults.
+
+## API Discovery
+
+Developers and coding agents should start with these package-owned docs:
+
+- [`docs/components/README.md`](./docs/components/README.md) lists every custom element, common attributes, typed properties, events, and template hooks.
+- [`docs/components/product-grid.md`](./docs/components/product-grid.md) documents search loading, sorting, paging, default query merging, and declarative query markup.
+- [`docs/components/product-rail.md`](./docs/components/product-rail.md) documents homepage/category rails and their query configuration.
+- [`AGENTS.md`](./AGENTS.md) gives coding agents the conventions for building shops with this package.
+- [`custom-elements.json`](./custom-elements.json) is the Custom Elements Manifest for tools that understand web component metadata.
+- [`html-custom-data.json`](./html-custom-data.json) is VS Code compatible custom data for HTML autocomplete and hover docs.
+
+Enable HTML editor hints in a consuming project by adding the package custom data file to `.vscode/settings.json`:
+
+```json
+{
+  "html.customData": [
+    "./node_modules/@orderlyshop/web-components/html-custom-data.json"
+  ]
+}
+```
+
+The most important convention is that Core contracts use typed JavaScript properties, while simple search use cases can be declared in HTML. For example:
+
+```html
+<orderly-product-rail
+  title="Sko"
+  cta-label="Se alle"
+  cta-href="/categories/sko/"
+  keywords="H&M"
+  tags="børnetøj,bluser"
+  order-by="CreatedTime desc">
+</orderly-product-rail>
+```
+
+## Default Shop
+
+The package can render a working default storefront with the built-in backend, navigation, sorting, basket, product detail, and footer defaults:
+
+```ts
+import "@orderlyshop/web-components/define";
+```
+
+```html
+<orderly-category-page></orderly-category-page>
+```
+
+The default backend is `https://service.orderly.shop`. Category links use real `/categories/<category-path>/` URLs by default so production builds can ship server-rendered category HTML. Use `categoryUrlMode: "hash"` only when a shop explicitly wants the older `/category.html#id=<category>` routing.
+
+Customize the default once per shop from the HTML head:
+
+```ts
+import { create } from "@bufbuild/protobuf";
+import { AccountIdSchema, SearchQuerySchema, UUIDSchema } from "@orderlyshop/core-client";
+import { configureShop } from "@orderlyshop/web-components";
+import { navigationDefinitions } from "./navigation";
+
+const defaultQuery = create(SearchQuerySchema, {
+  SourceAccountId: create(AccountIdSchema, {
+    Id: create(UUIDSchema, { Value: "00000000-0000-0000-0000-000000000000" })
+  }),
+  HiddenQuery: "published"
+});
+
+configureShop({
+  uiLanguage: "DA",
+  defaultShop: {
+    baseUrl: "https://service.orderly.shop",
+    defaultQuery,
+    brandLabel: "Example Shop",
+    homeHref: "/",
+    productHref: "/product.html",
+    navigationDefinitions,
+    sortOptions: [
+      { label: "Newest", orderBy: ["CreatedTime desc"] },
+      { label: "Price: low to high", orderBy: ["Price asc"] }
+    ]
+  },
+  pageLayout: {
+    logoSrc: "https://orderly.shop/home/App_Icon.svg",
+    logoAlt: "Example Shop",
+    logoHref: "/"
+  },
+  responsiveTemplates: {
+    mobileMediaQuery: "(max-width: 860px)"
+  }
+});
+```
+
+Use English built-in copy by changing only the top-level language:
+
+```ts
+configureShop({ uiLanguage: "EN" });
+```
+
+`defaultQuery` is a full Core `SearchQuery` and is merged into every `orderly-product-grid` request, including grids inside `orderly-category-page`, `orderly-collection-page`, and `orderly-product-rail`. A tenant account id is just one possible field on that query. Advanced shops can also assign `defaultQuery` directly on a specific component from JavaScript. User-facing category and search text stays in `SearchQuery.Query`; any text from the default query is moved to `HiddenQuery` so it still narrows results without replacing the visible search term.
+
+`configureShop()` validates `navigationDefinitions`. Every category needs an explicit globally unique `slug` using lowercase letters, numbers, and hyphens. If navigation is invalid, category pages render a visible configuration error that points at the broken item.
+
+```ts
+categoryPage.defaultQuery = defaultQuery;
+productGrid.defaultQuery = defaultQuery;
+productRail.defaultQuery = defaultQuery;
+```
+
+After that, category pages can stay declarative:
+
+```html
+<orderly-category-page slug="shoes/women"></orderly-category-page>
+<orderly-category-page slug="women"></orderly-category-page>
+<orderly-category-page></orderly-category-page>
+```
+
+When no category attribute is set, `orderly-category-page` resolves the category from the current URL. It supports `/category.html#id=shoes%2Fwomen` and generated path pages such as `/categories/shoes/women/`. Hash ids are matched against both the generated category id and each navigation item's slug.
+
+## Example Shop
+
+A complete vanilla HTML storefront example with strongly typed TypeScript navigation data is included in the npm package source at `examples/shop`.
+
+After installing from the repository workspace, run it with:
+
+```sh
+npm run dev --workspace @orderlyshop/example-shop
+```
+
+Inside an installed package, inspect the same reference implementation at:
+
+```text
+node_modules/@orderlyshop/web-components/examples/shop
+```
+
+The example demonstrates how to customize the package default with Danish navigation, shop copy, and declarative home/category/product/checkout pages while exercising the base component renderers directly. It intentionally avoids local CSS and templates while the package default look and feel is developed. Shared component configuration lives in `src/includes/head.html`; the strongly typed navigation data lives in `src/navigation.ts`. It uses the package-level `orderly-generate-category-pages` and `orderly-build-category-pages` commands for simple real-URL category pages. It is included as readable source code and is not exported as part of the runtime API.
+
+## Navigation Setup
+
+Installing `@orderlyshop/web-components` installs explicit shop and navigation helper tools. They do not run automatically during `npm install`.
+
+For a new shop, start with the full scaffold:
+
+```sh
+npx orderly-init-shop
+```
+
+Create only a default strongly typed `navigation.ts` in the current project when the shop scaffold already exists:
+
+```sh
+npx orderly-init-navigation
+```
+
+Create the file somewhere else:
+
+```sh
+npx orderly-init-navigation --path src/navigation.ts
+```
+
+Agent workflow for a new shop:
+
+1. Ask the user for the new shop's Orderly account id.
+2. Run the navigation helper to dump sampled product information:
+
+```sh
+npx orderly-init-navigation --suggest --account-id <account-id>
+```
+
+3. Read the generated `navigation-products.json`. The helper does not infer categories. It writes sampled product records with `title`, `brand`, and `tags` only, plus sampling metadata.
+4. Create `navigation.ts` manually from the dump. Export `navigationDefinitions: NavigationDefinition[]`. Each entry must have `label` and a stable, globally unique `slug`, and can also have optional `heroImage`, optional `description`, optional `query`, and optional recursive `children`. Use plain `SearchQueryInput` objects for `query`, such as `{ query: "sko sneakers", tags: ["sko"] }`.
+5. Keep navigation to at most two category levels. Categories should be reasonably granular, but avoid empty categories or categories backed by only a few products.
+6. Configure the shop scope with a Core `SearchQuery` and pass it to `configureShop({ defaultShop: { defaultQuery } })`.
+
+The helper is intentionally an explicit tool for developers and coding agents. It is not a postinstall action. Agents should keep user-owned navigation edits, ask before overwriting files, and treat the product dump as source material for human-reviewable navigation.
+
+Show tool help:
+
+```sh
+npx orderly-init-navigation --help
+```
+
+Optional flags:
+
+```sh
+npx orderly-init-navigation --suggest --account-id <account-id> --base-url https://service.orderly.shop --max-results 1000 --product-dump-path src/navigation-products.json
+```
+
+Use TypeScript output paths when the shop source is TypeScript:
+
+```sh
+npx orderly-init-navigation --suggest --account-id <account-id> --path src/navigation.ts --product-dump-path src/navigation-products.json
+```
+
+The product dump is sampled so large search indexes are not copied wholesale. It starts with every second product, then every third, fifth, eighth, and thirteenth product as the source result set grows. `--max-results` caps the number of product records written and defaults to `1000`.
+
+Navigation data has three layers:
+
+- `NavigationDefinition` is the authored data in `navigation.ts`. It is the only type most shops need to write. Every item needs an explicit stable `slug`; labels are display text and can change without changing URLs.
+- `ResolvedNavigationItem` is created by `createCategoryNavigation()` and consumed by default page components. It adds stable ids, hrefs, normalized Core `SearchQuery` values, and derived metadata.
+- `NavigationMetadata` contains those derived page values: slug, parent id, path segments, normalized query, search text, description, hero image, and page root.
+
+The older `CategoryDefinition`, `CategoryNavigationItem`, and `CategoryMetadata` names remain as compatibility aliases only.
+
+## Real Category URLs
+
+Installing `@orderlyshop/web-components` also installs generic category page tools. Real path category URLs are the default because they are the best fit for SEO and static/server-rendered category pages.
+
+Generate pages from the current shop's `src/navigation.ts` or `src/navigation.js` and category page template. If `src/category.html` exists, the generator uses it and writes generated source pages under `src/categories`; otherwise it falls back to `category.html` and `categories`:
+
+```sh
+npx orderly-generate-category-pages
+```
+
+Preview what would be generated:
+
+```sh
+npx orderly-generate-category-pages --dry-run
+```
+
+Remove generated pages:
+
+```sh
+npx orderly-generate-category-pages --clean
+```
+
+Build with generated category pages and then clean the generated source files. Scaffolded shops use this flow from `npm run build` by default:
+
+```sh
+npx orderly-build-category-pages
+```
+
+`orderly-build-category-pages` also hydrates the built `dist/index.html` and generated `dist/categories/**/index.html` pages with SEO-friendly fallback HTML. The hydration step embeds a small product snapshot per category using `SearchService.Search`; it reads `--base-url`, `VITE_ORDERLY_BASE_URL`, or `ORDERLY_BASE_URL`, and otherwise uses the default `https://service.orderly.shop` backend. Live web components hide the fallback when their client-side search data has loaded, so users avoid a blank category page while Google receives meaningful initial HTML.
+
+Hydrate an already-built site manually, for example in a nightly job:
+
+```sh
+npx orderly-hydrate-static-pages --base-url https://service.orderly.shop --products-per-category 12
+```
+
+Use `--skip-products` for metadata-only hydration, `--strict-products` when a nightly job should fail on backend search errors, and `--no-hydrate` on `orderly-build-category-pages` to keep the older unhydrated build behavior.
+
+The category generator expects `src/navigation.ts` or `src/navigation.js` to export `navigationDefinitions` and the template page to contain `<orderly-category-page></orderly-category-page>`. TypeScript navigation files use the current shop project's `typescript` dependency for one-off transpilation. Useful options include `--navigation`, `--template`, `--categories-dir`, `--site-title`, `--component-tag`, and `--export`. The older `--taxonomy` flag and `categoryDefinitions` export are still accepted as compatibility aliases.
+
+## Publish Static Sites
+
+Installing `@orderlyshop/web-components` also installs a publish command for the consuming shop project. Run it from the project directory. The command generates category pages, builds, hydrates the built homepage/category pages, and publishes the resulting `dist` folder as vanilla HTML/JS/CSS.
+
+Publish the current project to a local folder:
+
+```sh
+npx orderly-publish-site --target local --dir published-site
+```
+
+Opt out of generated category pages when a project has its own server-side category routing:
+
+```sh
+npx orderly-publish-site --target local --dir published-site --no-category-pages
+```
+
+Publish the current project over FTP:
+
+```sh
+npx orderly-publish-site --target ftp
+```
+
+The FTP target prompts for server URL, remote folder, username, and password when values are missing. Values are saved in `.orderly-publish.local.json` in the current project directory and reused on the next publish. Keep that file out of git; it is written with owner-only file permissions where the OS supports it.
+
+Re-enter saved FTP settings:
+
+```sh
+npx orderly-publish-site --target ftp --configure
+```
+
+## Server Side Product URLs
+
+Category pages can be generated and hydrated statically. Product pages usually need real URLs without generating one HTML file per product. The package ships server helper files under `server/` for this pattern:
+
+- `server/apache/.htaccess` rewrites unknown product-like `.html` URLs to PHP.
+- `server/php/orderly-product.php` reuses the built `product.html`, injects declarative SSR fallback markup into `<orderly-product-detail-page>`, and preserves built JS/CSS references.
+- `server/nginx/orderly-products.conf` provides the equivalent Nginx rewrite for PHP-FPM.
+- `server/node/product-snapshot-server.mjs` is an optional Node snapshot endpoint that calls `SearchService.Search` through `@orderlyshop/core-client` and returns product title, brand, price, image, and description as JSON.
+
+Apache deployment example:
+
+```sh
+npm run build
+cp node_modules/@orderlyshop/web-components/server/apache/.htaccess dist/.htaccess
+cp node_modules/@orderlyshop/web-components/server/php/orderly-product.php dist/orderly-product.php
+```
+
+If PHP should SSR real product fields, configure a server-side snapshot endpoint:
+
+```sh
+ORDERLY_BACKEND_URL=https://service.orderly.shop \
+node node_modules/@orderlyshop/web-components/server/node/product-snapshot-server.mjs
+
+export ORDERLY_PRODUCT_SNAPSHOT_ENDPOINT=http://127.0.0.1:4107/orderly-product-snapshot
+```
+
+The PHP renderer emits a small declarative fallback with `data-orderly-ssr-fallback`; `orderly-product-detail-page` hides that fallback when the browser has loaded the live `SearchObject`. See [`server/README.md`](./server/README.md) for Apache, Nginx, PHP, Node, caching, and SEO notes.
+
+## Define Elements
+
+```ts
+import { configureShop } from "@orderlyshop/web-components";
+
+configureShop({
+  responsiveTemplates: { mobileMediaQuery: "(max-width: 860px)" },
+  storedImageUrls: { baseUrl: "https://static.example-cdn.com/" }
+});
+```
+
+Use a custom prefix when a shop already owns the default tag names:
+
+```ts
+configureShop({ components: { prefix: "shop" } });
+```
+
+The side-effect entrypoint registers the default `orderly-*` tags:
+
+```ts
+import "@orderlyshop/web-components/define";
+```
+
+The package installs baseline storefront CSS and structural lazy-load CSS when components are registered. The baseline CSS gives the default light-DOM components usable layout, spacing, responsive behavior, and product presentation without requiring a shop-owned stylesheet. Host shops can override it with normal CSS variables and `orderly-*` class selectors.
+
+The lazy-load CSS can also be included as early as possible in the document head when pages contain slotted light-DOM content and need to avoid pre-hydration flashes:
+
+```ts
+import { ORDERLY_LAZY_LOAD_CSS } from "@orderlyshop/web-components";
+
+const style = document.createElement("style");
+style.textContent = ORDERLY_LAZY_LOAD_CSS;
+document.head.append(style);
+```
+
+`defineOrderlyWebComponents()` installs the same lazy-load CSS at runtime as a fallback, but head inclusion is what prevents raw slotted links from flashing before JavaScript has loaded. The default component CSS is exported as `ORDERLY_DEFAULT_CSS` and installed automatically by `defineOrderlyWebComponents()`.
+
+## Global Templates
+
+Templates can live next to a specific element or in a shared page-level registry. Local templates still win, but components also look for document-level templates with `data-orderly-for`, `data-orderly-component`, or `data-orderly-template-scope`.
+
+```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>
+    <p data-orderly-bind="price"></p>
+    <button type="button" data-orderly-action="add-to-basket">
+      <span data-orderly-bind="basket-action-icon"></span>
+    </button>
+  </article>
+</template>
+```
+
+This is useful for vanilla shops that include shared snippets such as `body-start.html`; all shop-specific templates can be included there instead of being repeated on every category page. A shop can keep each template in `src/templates/*.html` and use build-time comments such as `<!-- orderly-include-template: ../templates/product-tile.html -->` from `body-start.html`. `data-orderly-for` can target a full tag name such as `orderly-product-tile`, a prefix-independent component name such as `product-tile`, or `*`. Responsive global templates support the same `data-orderly-viewport` and `data-orderly-media` attributes as local templates.
+
+JavaScript can also register templates:
+
+```ts
+import { registerGlobalTemplate } from "@orderlyshop/web-components";
+
+registerGlobalTemplate({
+  name: "product",
+  for: "product-tile",
+  template: `<article><h3 data-orderly-bind="title"></h3></article>`
+});
+```
+
+## Collection Page
+
+```html
+<orderly-collection-page
+  id="collection"
+  title="Summer collection"
+  description="Light layers and one-off pieces"
+  hero-image="/images/summer.jpg">
+  <template data-orderly-template="product">
+    <article class="product-card">
+      <orderly-product-tile></orderly-product-tile>
+    </article>
+  </template>
+</orderly-collection-page>
+```
+
+```ts
+import { create } from "@bufbuild/protobuf";
+import { SearchQuerySchema } from "@orderlyshop/core-client";
+import { createOrderlyWebClient } from "@orderlyshop/core-client/web";
+
+const client = createOrderlyWebClient({ baseUrl: "https://api.orderly.example" });
+const searchQuery = create(SearchQuerySchema, {
+  Term: "summer"
+});
+
+collection.client = client;
+collection.query = searchQuery;
+```
+
+## Components
+
+- `orderly-page-layout` provides reusable page regions for header, header actions, left/right sidebars, content, footer, and overlay content. It includes a default logo image using `https://orderly.shop/home/App_Icon.svg`; override it with `logo-src`, `logo-alt`, and `logo-href`.
+- `orderly-home-page` composes page layout, side navigation, one product rail per top-level category, basket icon, basket drawer, product detail dialog, and footer. Configure it with `configureShop({ defaultShop })` plus attributes such as `title`, `eyebrow`, `rail-cta-label`, and `product-href`. The product dialog includes an expand icon link to `product-href#url=<encoded-share-url>`; `https://orderly.shop/` is stripped from Orderly product URLs before encoding.
+- `orderly-category-page` composes page layout, navigation, search, product grid, product detail, basket icon, and basket around a navigation category. Without properties it uses the package default shop configuration. Override with `configureShop({ defaultShop })` once per shop, set `base-url` or `product-href` in markup, or assign `category`, `navigationItems`, `sortOptions`, `client`, `defaultQuery`, and `basketController` from JavaScript for advanced cases. The product dialog includes an expand icon link built from `SearchObject.ShareURL.URL`, using compact hashes for `https://orderly.shop/...` product URLs.
+- `orderly-checkout-page` composes page layout, side navigation, checkout form, basket order summary, footer, shared basket state, delivery loading, and order-created cleanup. Delivery methods render as radio cards after address entry, service points render as radio-card pickup choices when required, and delivery changes verify the draft so totals update. Configure copy through `configureShop({ defaultShop: { checkoutPageTitle, checkoutPageDescription, checkoutOrderTitle, checkoutTermsHref, checkoutLabels, basketLabels } })`, or assign `client`, `basketController`, `navigationItems`, `checkoutLabels`, and `basketLabels` from JavaScript.
+- `orderly-product-detail-page` composes page layout, navigation, product detail, basket drawer, and footer for a product route. Set `share-url`, the `shareUrl` property, or pass `#url=<encoded-share-url>` in the page URL; compact Orderly slugs are restored to `https://orderly.shop/...` before it calls `SearchService.Search` with `SearchQuery.ShareUrl` and renders the resolved `SearchObject`.
+- `orderly-stored-image` accepts `image: StoredImage`, resolves image URLs from the configured prefix, and applies `RotationDeg`, crop, and full-size metadata in the browser.
+- `orderly-credit` accepts `credit: Credit` or declarative `amount` and `currency` attributes, then renders stylable money markup. DKK values are formatted as `kr. <pris>`, for example `kr. 100,00`.
+- `orderly-product-tile` accepts `product: SearchObject` and emits `orderly-product-selected`, `orderly-add-to-basket`, and `orderly-remove-from-basket`. Templates can bind the product share URL with `data-orderly-bind="share-url"`; anchors receive `href` and other elements receive `share-url`. If an anchor already has `href="/product.html"`, the bound link becomes `/product.html#url=<encoded-share-url>`, using the compact path for `https://orderly.shop/...` product URLs. Default tiles and statically hydrated category tiles include `schema.org/Product` and `schema.org/Offer` microdata for name, image, URL, description, SKU, brand, price, currency, and in-stock availability when those fields are present. When a `BasketController` is assigned through `basketController`, the default action button toggles between add and remove, using an icon-only button next to the price.
+- `orderly-product-page` accepts `product: SearchObject`, renders all product image thumbnails, switches the selected image on thumbnail click, and exposes product details plus add-to-basket behavior.
+- `orderly-search-box` binds to a target `orderly-product-grid`. Use `mode="textbox"` for an inline search input or `mode="icon"` for a header icon that opens a full-page search overlay. Icon mode searches automatically with a 500ms debounce and renders matching product tiles below the search field. Default home and category pages use icon mode next to the basket icon.
+- `orderly-product-grid` accepts `query: SearchQuery`, merges the configured shop query scope, calls `SearchService.Search`, renders its own sort control from `sortOptions`, supports opaque `ContinuationToken` paging, manual paging, dynamic/infinite scroll, and default loading placeholders while the first page is pending.
+- `orderly-product-rail` accepts `query: SearchQuery`, title, CTA label, and CTA href, then renders the search as a horizontal scroll list by composing `orderly-product-grid`. It is useful for homepages and editorial rows where several category searches should be stacked vertically.
+- `orderly-collection-page` accepts `query: SearchQuery`, title, description, and hero image, then delegates fetching to `orderly-product-grid`.
+- `orderly-shop-footer` renders configurable logo, about text, address, contact information, opening hours, and information links.
+- `orderly-basket-icon` and `orderly-basket` share a `BasketController` backed by `DraftOrder` persistence. Basket state events such as `orderly-basket-open`, `orderly-basket-change`, and `orderly-basket-verified` use the current `DraftOrder` directly as `event.detail`, so consumers can derive counts and totals from Core contracts instead of an internal basket data shape. `orderly-basket` renders an item overview, verifies changed drafts through `OrderService.VerifyDraft` when a client or `base-url` is configured, includes a configurable checkout link through `checkout-href` and `checkout-label`, and only exposes quantity selection for lines where `MaxQuantity > 1`.
+- `orderly-checkout` persists checkout profile fields, looks up Danish city names from the entered postal code through Dataforsyningen's `https://api.dataforsyningen.dk/postnumre/{postnr}` endpoint, loads delivery methods and service points, verifies the draft, and calls `OrderService.Create`.
+- `orderly-navigation` uses `NavigationController` and can be subclassed with site-specific `NavigationItem[]`. It is sticky by default, including when placed in `left`, `right`, or `primary-nav`; set `sticky="false"` to opt out.
+- `orderly-search-box`, `orderly-sort-select`, `orderly-filter-panel`, and `orderly-load-more` bind to `orderly-product-grid`.
+
+## Rendering And Styling
+
+The package ships baseline default CSS and uses light DOM. Default markup uses stable `orderly-*` class names and CSS variables such as `--orderly-color-accent`, `--orderly-color-page`, `--orderly-color-surface`, `--orderly-color-text`, `--orderly-color-muted`, and `--orderly-content-max-width`, so host CSS can style or replace the default look directly.
+
+Rendering can be replaced with templates:
+
+```html
+<orderly-page-layout>
+  <template data-orderly-template="layout">
+    <section class="shop-layout">
+      <header data-orderly-slot="header"></header>
+      <aside data-orderly-slot="left"></aside>
+      <main data-orderly-slot="content"></main>
+      <footer data-orderly-slot="footer"></footer>
+    </section>
+  </template>
+
+  <a slot="header" href="/">Shop</a>
+  <shop-navigation slot="left"></shop-navigation>
+  <orderly-collection-page slot="content"></orderly-collection-page>
+</orderly-page-layout>
+
+<orderly-page-layout
+  logo-src="/brand/logo.svg"
+  logo-alt="Example shop"
+  logo-href="/">
+  <a slot="header" href="/">Example shop</a>
+  <orderly-shop-footer slot="footer"></orderly-shop-footer>
+</orderly-page-layout>
+
+<orderly-product-grid id="grid" paging="dynamic">
+  <template data-orderly-template="layout">
+    <section class="catalog">
+      <div data-orderly-slot="sort"></div>
+      <p data-orderly-bind="status"></p>
+      <ol data-orderly-slot="items"></ol>
+      <span data-orderly-sentinel></span>
+    </section>
+  </template>
+  <template data-orderly-template="empty">
+    <p class="empty-state">No matches.</p>
+  </template>
+  <template data-orderly-template="product">
+    <li class="catalog-item">
+      <orderly-product-tile></orderly-product-tile>
+    </li>
+  </template>
+</orderly-product-grid>
+```
+
+For dynamic paging, `orderly-product-grid` keeps the returned `PageResult.Continuation` as an opaque `ContinuationToken` and sends it as `SearchQuery.Continuation` when the sentinel enters the viewport. Dynamic and infinite paging do not render a load-more button. Use `paging="button"` only when a visible load-more button is desired, `paging="manual"` when another control calls `loadNextPage()`, and `paging="dynamic"` or `paging="infinite"` for automatic loading.
+
+Every component has a default light-DOM implementation and matching template hooks. Use `data-orderly-bind` for values, `data-orderly-action` for behavior, and `data-orderly-slot` for repeated or projected content. Product tile templates can bind `basket-action-icon`, `basket-action-label`, and `basket-action-state` and use `data-orderly-action="add-to-basket"` for the add/remove toggle. Product page galleries use `data-orderly-slot="thumbnails"` and `data-orderly-action="select-image"` for custom thumbnail markup. Product rail templates can replace the outer `layout`, inner `grid`, product item, loading state, and empty state. The main template names are `layout`, `grid`, `footer`, `product`, `thumbnail`, `image`, `basket`, `basket-icon`, `line`, `checkout`, `navigation`, `item`, `search-box`, `sort`, `sort-select`, `filter-panel`, `load-more`, `address-line`, `contact-item`, `opening-hour`, and `information-link`.
+
+Product sorting belongs to `orderly-product-grid`: assign `grid.sortOptions = [{ label, orderBy }]` or pass sort options through `orderly-collection-page.sortOptions`. The default grid layout renders the sort select above the products. Custom grid layouts should include `data-orderly-slot="sort"` where the control should appear, and custom sort templates can use `data-orderly-template="sort"` with a `<select data-orderly-action="sort">`.
+
+Simple product queries can be declared in markup on `orderly-product-grid`, `orderly-product-rail`, and `orderly-collection-page`:
+
+```html
+<orderly-product-rail
+  title="Sko"
+  cta-label="Se alle"
+  cta-href="/categories/sko/"
+  keywords="H&M"
+  tags="børnetøj,bluser"
+  order-by="CreatedTime desc">
+</orderly-product-rail>
+```
+
+The same query can be grouped as child markup:
+
+```html
+<orderly-product-rail
+  title="Sko"
+  cta-label="Se alle"
+  cta-href="/categories/sko/">
+  <query>
+    <tags>børnetøj,bluser</tags>
+    <keywords>H&M</keywords>
+    <order-by>CreatedTime desc</order-by>
+  </query>
+</orderly-product-rail>
+```
+
+Declarative query fields map to `SearchQuery.Query`, `SearchQuery.Tags`, `SearchQuery.HiddenQuery`, `SearchQuery.OrderBy`, `SearchQuery.StoreId`, and `SearchQuery.Featured`. For the full Core contract, assign the typed `query` property from JavaScript.
+
+Templates can be viewport-specific on every component:
+
+```html
+<orderly-product-page>
+  <template data-orderly-template="product" data-orderly-viewport="desktop">
+    <section class="product-detail product-detail--desktop">
+      <div data-orderly-slot="thumbnails"></div>
+      <orderly-stored-image data-orderly-bind="image" variant="object"></orderly-stored-image>
+    </section>
+  </template>
+  <template data-orderly-template="product" data-orderly-viewport="mobile">
+    <section class="product-detail product-detail--mobile">
+      <orderly-stored-image data-orderly-bind="image" variant="object"></orderly-stored-image>
+      <div data-orderly-slot="thumbnails"></div>
+    </section>
+  </template>
+  <template data-orderly-template="thumbnail">
+    <button type="button" data-orderly-action="select-image">
+      <orderly-stored-image data-orderly-bind="thumbnail"></orderly-stored-image>
+    </button>
+  </template>
+</orderly-product-page>
+```
+
+Use `data-orderly-viewport="mobile"` or `data-orderly-viewport="desktop"` for the package breakpoint, or `data-orderly-media="(max-width: 540px)"` for a component-specific media query. Components rerender when the viewport crosses the configured breakpoint. The default mobile breakpoint is `767px` and can be changed once per app:
+
+```ts
+import { configureShop } from "@orderlyshop/web-components";
+
+configureShop({ responsiveTemplates: { mobileMediaQuery: "(max-width: 860px)" } });
+```
+
+`orderly-page-layout` can also be changed once per shop without touching every category page:
+
+```ts
+import { configureShop } from "@orderlyshop/web-components";
+
+configureShop({
+  pageLayout: {
+    template: `
+      <section class="custom-shop-layout">
+        <header data-orderly-slot="header"></header>
+        <main data-orderly-slot="content"></main>
+        <footer>
+          <orderly-shop-footer></orderly-shop-footer>
+          <div data-orderly-slot="footer"></div>
+        </footer>
+        <aside data-orderly-slot="right"></aside>
+        <div data-orderly-slot="overlay"></div>
+      </section>
+    `
+  }
+});
+```
+
+Shop-specific footer content is usually clearer as a global template in shared HTML, for example `body-start.html`:
+
+```html
+<template data-orderly-template="footer" data-orderly-for="shop-footer">
+  <div class="orderly-shop-footer">
+    <div class="orderly-shop-footer__brand">
+      <a class="orderly-shop-footer__logo" href="/" aria-label="Example shop">
+        <img class="orderly-shop-footer__logo-image" src="/brand/logo.svg" alt="Example shop">
+      </a>
+      <p class="orderly-shop-footer__about">Independent shop copy.</p>
+    </div>
+    <section class="orderly-shop-footer__section" aria-labelledby="footerInfo">
+      <h2 id="footerInfo" class="orderly-shop-footer__heading">Information</h2>
+      <ul class="orderly-shop-footer__list">
+        <li class="orderly-shop-footer__link-item">
+          <a class="orderly-shop-footer__link" href="/delivery/">Delivery</a>
+        </li>
+      </ul>
+    </section>
+  </div>
+</template>
+```
+
+Typed JavaScript properties are used for Core contracts and clients. Attributes are limited to primitive configuration such as `base-url`, `paging`, `title`, `description`, `hero-image`, `logo-src`, `logo-alt`, `logo-href`, `fit`, `variant`, and `for`.
+
+Basket checkout navigation is configured in markup:
+
+```html
+<orderly-basket checkout-href="/checkout.html" checkout-label="Go to checkout"></orderly-basket>
+```
+
+Stored images can be rendered directly:
+
+```html
+<orderly-stored-image id="productImage" fit="cover" variant="thumbnail"></orderly-stored-image>
+```
+
+```ts
+productImage.image = searchObject.Images[0];
+```
+
+`orderly-stored-image` uses `DEFAULT_IMAGE_BASE_URL`, currently `https://orderlyproduction.azureedge.net/`, when no custom image URL configuration is supplied. `configureStoredImageUrls({ baseUrl })` maps normal product images to `baseUrl/thumbnails/<StoredImage.Name>` and full/object variants to `baseUrl/objects/<StoredImage.Name>`. The component also supports `ImageDataBase64`, absolute URLs, and a custom resolver through `configureStoredImageUrls({ resolver })`.
+
+## State And Security
+
+Basket drafts and checkout profile fields are persisted to localStorage by default. Checkout profile data can include PII such as name, address, email, and phone. Provide custom stores to change or disable that behavior. This package never stores tokens, API keys, OAuth responses, or cookie values.
+
+Basket persistence uses `LocalStorageBasketStore`. Checkout profile persistence uses `LocalStorageCheckoutProfileStore`. Both can be replaced:
+
+```ts
+import { createBasketController } from "@orderlyshop/web-components";
+
+basket.basketController = createBasketController({ store: myBasketStore });
+checkout.profileStore = myCheckoutProfileStore;
+```
+
+Authentication remains owned by `@orderlyshop/core-client`. Browser cookie-backed sessions work through the core browser client and credentialed gRPC-web requests.