@zappie/verify 0.3.0 → 0.3.2

package/CHANGELOG.md

@@ -1,5 +1,22 @@
 # @zappie/verify
 
+## 0.3.2
+
+### Patch Changes
+
+- b0b2a59: Let a site raise V15's first-card tappable limit to 5000 ms with an explained site budget, and record the applied limit in the verify report. A site that adds `budgets.tappableMs` must upgrade `@zappie/check` and `@zappie/sdk` in the same change.
+- 4f1ef9e: Make V03 count an item marker only when shoppers can see its item name and expected price.
+- Updated dependencies [b0b2a59]
+  - @zappie/sdk@0.1.15
+
+## 0.3.1
+
+### Patch Changes
+
+- 0b31798: V03 accepts a card that shows an item's starting price. When `showsFromPrice` from `@zappie/sdk/pricing` is true for an item, its card can show `startingPrice`, with or without "From", as well as the item's price. Before, V03 failed a card that showed "From ₦9,700" for an item priced ₦8,500 with a required choice.
+- 0b31798: V05 finds a required option group by `data-zappie-required="true"` as well as `aria-required="true"`. A required group that takes several choices has no `aria-required`, because ARIA doesn't allow it on `role="group"`, so before V05 failed it with `required_group_missing`. Sites on an older `@zappie/foundations` still pass on `aria-required`. When Add stays enabled and the only unmet required group takes a typed answer, V05 no longer waits for a group of choices to flag.
+- 0b31798: `verify.startPath` and `--start` take `{menu}` and `{branch}`, as `cataloguePath` does. `{menu}` becomes the id of the first menu that holds items, in the order V03 judges menus, and `{branch}` the id of the default branch. Set `/menu?menu={menu}` for a site whose menu page asks the shopper to choose a menu. The report records the filled path in `environment.startPath` and the path as written in `environment.startPathTemplate`. Without `cataloguePath`, V03 judges only the start menu's items on the start page. The item checks still open the start page, so set `cataloguePath` too when their items can sit on another menu. With `--start`, `zappie` 0.1.8 or later checks that verify filled the path.
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -46,10 +46,10 @@ export default {
 } satisfies ZappieSiteConfig;
 ```
 
-- `startPath` is the route verify opens wherever it opened `/`. It must list items. `--start` wins over it.
+- `startPath` is the route verify opens wherever it opened `/`. It must list items. `--start` wins over it. It can name a menu with `{menu}` and the branch with `{branch}`, as `cataloguePath` does. `{menu}` becomes the id of the first menu that holds items, in the order V03 judges menus, and `{branch}` the id of the default branch. Use it for a site whose menu page asks the shopper to choose a menu, such as `/menu?menu={menu}`. Without `cataloguePath`, V03 judges only that menu's items on the start page. The item checks still open the start page, so set `cataloguePath` too when the item they use can sit on another menu.
 - `cataloguePath` is the page of each menu: `{menu}` stands for the menu id and `{branch}`, when you use it, for the branch id. With it, V03 opens every menu's page and needs 95% of that menu's available items on it, instead of 95% of the branch's items on one page. V04, V05, V13, V16 and V17 open the page of a menu that holds the item they use. An item that sits in no category of any menu belongs to no menu's page, so V03 doesn't judge it.
 
-Without them, verify runs as before. The report's `environment` records `startPath`, and `cataloguePath` when it is set.
+Without them, verify runs as before. The report's `environment` records `startPath`, and `cataloguePath` when it is set. A `startPath` with `{menu}` or `{branch}` is recorded filled in, and as written in `startPathTemplate`.
 
 ### Chromium
 
@@ -81,10 +81,12 @@ const report = await verifyProject({
 console.log(printSummary(report));
 ```
 
-`verifyProject` also takes `build: false`, `port`, `only`, `startPath`, `cataloguePath`, `runner`, `artifactsDir` and `browserExecutablePath`, the options behind the flags above. It reads `startPath` and `cataloguePath` from `zappie.config.ts` when you don't pass them. To verify a site you serve yourself, call `verify({ url, key, store, suite })` instead, with `startPath` and `cataloguePath` when the site sets them.
+`verifyProject` also takes `build: false`, `port`, `only`, `startPath`, `cataloguePath`, `tappableMs`, `runner`, `artifactsDir` and `browserExecutablePath`, the options behind the flags above. It reads `startPath`, `cataloguePath` and `budgets.tappableMs` from `zappie.config.ts` when you don't pass them. To verify a site you serve yourself, call `verify({ url, key, store, suite })` instead, with the same route and tappable settings when the site sets them.
 
 The report's shape is the JSON Schema at `@zappie/verify/schema/verify-report.v1.json`.
 
+V15 uses a 3000 ms limit for the first product card to become tappable. A site can raise it to at most 5000 ms with `budgets.tappableMs` and must explain the exception in `budgets.override.reason`. A lower value keeps the 3000 ms default. The report records the applied limit as `metrics.productCardTappableLimitMs`.
+
 ## Markers
 
 The checks find shopping controls by their `data-zappie-*` markers, the ones the `zappie/verify-markers` lint rule and the template standards ask for, not by their labels, so your copy is yours to write. Where no marker names a control, a check uses its role. Text is read in three places only: V03 counts an item by its name when its card has no marker, V10 picks the address it typed from the suggestions, and V13 closes an item by a button whose name contains "Close".
@@ -93,6 +95,8 @@ They accept either way of building a journey where templates differ:
 
 - **Opening an item.** When the element marked `data-zappie-item` is a link or button, as on a card that is the link, the checks tap it. Otherwise they tap the first link inside the marked card, then the first link beside it.
 - **The cart control.** `data-zappie-cart-trigger`, or on a template that marks only its overlays, the visible `data-zappie-overlay-trigger="bag"` control.
+- **Item coverage and prices (V03).** A `data-zappie-item` marker counts when it is rendered, is not hidden by HTML, CSS or `aria-hidden`, has a non-zero box, and contains the item's name and price. Items in a scrollable page or container count when shoppers can reveal them by scrolling. A card shows the item's price in `format.money`. When `showsFromPrice` from `@zappie/sdk/pricing` is true, it can show the item's `startingPrice` instead, with or without "From".
+- **Required groups (V05).** A required option group is marked `data-zappie-option-group` and `data-zappie-required="true"`, as `OptionGroup` from `@zappie/foundations` marks single and multi-select groups. `aria-required="true"` on a single-select group also counts.
 - **Required options (V05).** Add can be disabled until every required choice is made. Or it can stay enabled: a tap then adds nothing, keeps the item open and marks the group with `aria-invalid` or `data-invalid` and a visible message, in the group, in its `aria-describedby` or `aria-errormessage` target, or in a `role="alert"` in the dialog.
 - **The quoted total (V06).** `data-zappie-total` in the bag, or, when the bag hands over to a checkout page through `data-zappie-cart-checkout` or a link to `/checkout`, on that page.
 - **A cart column (V13).** On a screen 768 px or wider, a cart the page always shows, with no visible cart control, is scanned with the page. V13 then skips opening it and the focus-return check for it. On a phone the cart control is still required.

package/dist/index.d.ts

@@ -49,6 +49,11 @@ type VerifyReport = {
          * started at `/`. Metrics measured from different start paths don't compare.
          */
         startPath?: string;
+        /**
+         * The start path as configured, with its `{menu}` or `{branch}`, when it had either.
+         * `startPath` is that path filled in.
+         */
+        startPathTemplate?: string;
         /** The catalogue path V03 and the item checks used, when the run had one. */
         cataloguePath?: string;
     };
@@ -80,6 +85,8 @@ type VerifyReport = {
         lcpMs?: number;
         cls?: number;
         productCardTappableMs?: number;
+        /** The site-specific limit V15 used for productCardTappableMs. */
+        productCardTappableLimitMs?: number;
         productCardOpenMs?: number;
         menuCssKbGz?: number;
         /** Tap to first paint of each marked overlay, by its `data-zappie-overlay` name: the median of its samples. */
@@ -102,7 +109,11 @@ type VerifyOptions = {
     only?: string[];
     /**
      * The route verify opens as the storefront's menu, such as `/menu`, for a site whose root is
-     * a directory rather than a menu. It must list items. Defaults to `/`.
+     * a directory rather than a menu. It must list items. Defaults to `/`. `{menu}` stands for
+     * the first menu that holds items, as V03 orders them, and `{branch}` for the default branch,
+     * such as `/menu?menu={menu}`. Without `cataloguePath`, V03 then judges only that menu's items
+     * on the start page, and the item checks still open the start page, so set `cataloguePath`
+     * too when the items they use can sit on another menu.
      */
     startPath?: string;
     /**
@@ -112,6 +123,8 @@ type VerifyOptions = {
      * judges every item of the branch on the start page.
      */
     cataloguePath?: string;
+    /** V15's first-card tappable limit. Values below 3000 use the 3000 ms default. */
+    tappableMs?: number;
     /** Findings about the run to record in the report's `warnings`. */
     warnings?: {
         code: string;