@orderlyshop/web-components 0.1.0

package/AGENTS.md

@@ -0,0 +1,110 @@
+# Agent Guide For `@orderlyshop/web-components`
+
+Use this package as a headless storefront component library. Prefer native custom elements, light-DOM templates, and normal CSS over framework-specific wrappers unless the user asks for a framework integration.
+
+## Discovery
+
+- Read `README.md` for setup and package-wide concepts.
+- Read `docs/components/README.md` for component APIs.
+- Read `docs/components/product-rail.md` and `docs/components/product-grid.md` before implementing product listing UI.
+- Read `custom-elements.json` for machine-readable custom element metadata.
+- Read `html-custom-data.json` when generating vanilla HTML or configuring editor autocomplete.
+- Inspect `examples/shop` for a complete vanilla TypeScript shop that customizes the defaults without replacing package logic.
+- When creating a new shop from scratch, run `npx orderly-init-shop` first. It scaffolds the vanilla HTML/TypeScript/Vite structure that the package expects, including `src/includes/head.html`, `src/navigation.ts`, `src/shop-query.ts`, page templates, and package scripts.
+
+## Query Rules
+
+- Use `configureShop({ defaultShop: { defaultQuery } })` for shop-wide query scope. `defaultQuery` is a full Core `SearchQuery`.
+- Do not create package-specific account id shortcuts. Tenant scoping is just `SearchQuery.SourceAccountId`.
+- For simple markup-driven searches, use declarative query attributes:
+  - `keywords` maps to `SearchQuery.Query`.
+  - `tags` maps to `SearchQuery.Tags`.
+  - `hidden-query` maps to `SearchQuery.HiddenQuery`.
+  - `order-by` maps to `SearchQuery.OrderBy`.
+  - `store-id` maps to `SearchQuery.StoreId`.
+  - `featured` maps to `SearchQuery.Featured`.
+- The same query values can be grouped inside a child `<query>` element.
+- Use typed JavaScript properties for full Core contracts:
+  - `query: SearchQuery`
+  - `defaultQuery: SearchQuery`
+  - `client: OrderlyClient`
+  - `basketController: BasketController`
+- In vanilla browser scripts, use `OrderlyWebComponents.createSearchQuery({ query, tags, orderBy })` from the standalone bundle when you need a SearchQuery without importing protobuf helpers.
+
+## Implementation Defaults
+
+- Keep components headless. Add behavior and default light-DOM markup, not bundled theme CSS.
+- Built-in UI copy defaults to Danish. Use `configureShop({ uiLanguage: "EN" })` for English shops, and prefer shop attributes/templates for wording that is unique to one storefront.
+- Preserve template override support through `data-orderly-template`, `data-orderly-bind`, `data-orderly-slot`, and `data-orderly-action`.
+- Put shop-wide templates in a shared document-level registry, for example template files included from `body-start.html`, using `data-orderly-template` plus `data-orderly-for`.
+- Keep browser-only package code free of Node HTTP modules.
+- Do not store tokens, API keys, OAuth responses, or cookie values.
+- Treat localStorage basket and checkout profile data as user-owned state. Do not add secret persistence.
+- Product images should default to `fit="contain"`, white background, and square aspect ratio in product tiles.
+- Product grids should support continuation-token based dynamic paging without requiring a visible load-more button.
+- Use `orderly-home-page` for default storefront homepages instead of generating product rails in app code.
+- Use `orderly-category-page` for category routes. Default category links should use `/categories/<category-path>/` so builds can generate and hydrate server-rendered category pages. Use `/category.html#id=<encoded-category-path-or-slug>` only for shops that explicitly opt into hash routing.
+- Keep `orderly-navigation` sticky by default. Use `sticky="false"` only when a shop intentionally wants navigation to scroll away.
+- Use `orderly-checkout-page` for checkout pages instead of wiring `orderly-checkout` and `orderly-basket` manually in app code.
+- Use `orderly-product-detail-page` for full product routes. Set `share-url` to the product `SearchObject.ShareURL.URL`; the component loads the product through `SearchQuery.ShareUrl`.
+- Keep category page generation in the normal shop build. Use `orderly-build-category-pages` without `--no-hydrate` so homepage/category pages get initial HTML for SEO and less visible loading shift. Pass `--base-url` or set `VITE_ORDERLY_BASE_URL` to override the default `https://service.orderly.shop` snapshot backend.
+- For real product URLs on traditional hosting, use the package-owned helpers in `server/`: Apache `.htaccess`, Nginx rewrite config, PHP product renderer, and optional Node product snapshot endpoint. Do not copy this logic into example-shop.
+- Use `navigation.ts` for shop category/navigation structure. Export `navigationDefinitions: NavigationDefinition[]`.
+- Use `npx orderly-init-navigation` to create the default file or `npx orderly-init-navigation --suggest --account-id <account-id>` to dump sampled product data for agent-assisted navigation design.
+- Navigation definitions are recursive but should stay at most two category levels deep for normal shops. Each item must include `label` and a stable globally unique `slug`, and can include optional `heroImage`, optional `description`, optional `query`, and optional `children`.
+- Use plain `SearchQueryInput` objects in navigation definitions, for example `query: { query: "sko sneakers", tags: ["sko"] }`.
+
+## Common Patterns
+
+Declarative product rail:
+
+```html
+<orderly-product-rail
+  title="Sko"
+  cta-label="Se alle"
+  cta-href="/categories/sko/"
+  keywords="H&M"
+  tags="børnetøj,bluser">
+</orderly-product-rail>
+```
+
+Structured query markup:
+
+```html
+<orderly-product-rail title="Sko">
+  <query>
+    <tags>børnetøj,bluser</tags>
+    <keywords>H&M</keywords>
+    <order-by>CreatedTime desc</order-by>
+  </query>
+</orderly-product-rail>
+```
+
+Typed query setup:
+
+```ts
+import { create } from "@bufbuild/protobuf";
+import { SearchQuerySchema } from "@orderlyshop/core-client";
+
+productRail.query = create(SearchQuerySchema, {
+  Query: "H&M",
+  OrderBy: ["CreatedTime desc"]
+});
+```
+
+Standalone browser setup:
+
+```html
+<script src="/node_modules/@orderlyshop/web-components/dist/browser/orderly-web-components.global.js"></script>
+<script>
+  const { configureShop } = OrderlyWebComponents;
+  configureShop({
+    uiLanguage: "DA",
+    defaultShop: {
+      navigationDefinitions: [
+        { label: "Sko", slug: "sko", query: { query: "sko sneakers" } }
+      ]
+    }
+  });
+</script>
+```