@stapel/reviews-react 0.1.0 → 0.2.0

package/CHANGELOG.md

@@ -1 +1,68 @@
 # @stapel/reviews-react
+
+## 0.2.0
+
+### Minor Changes
+
+- 23eeaff: New pair: `@stapel/reviews-react` — ratings and reviews of an opaque
+  `(target_type, target_key)`, with the four lies the contract makes easy
+  refused once, here, instead of being rediscovered per host.
+
+  - **A zero average is not a zero rating.** `GET /reviews/aggregate` answers
+    `{"avg": 0.0, "count": 0}` for a target nobody has rated, and its own schema
+    says so. `ratingSummary()` reports `rated: false` there — and has no `avg` on
+    that branch of the type — so a star row cannot be drawn from it. Same class
+    as `data ?? []`: a number that was never measured, displayed as if it had
+    been measured and found to be the worst possible score.
+  - **"You have already reviewed this" is a 400.** It is
+    `error.400.reviews_duplicate_review`, while the module's ONLY 409
+    (`error.409.reviews_already_responded`) is about the seller's reply — so a
+    form branching on the status misses the first and mishandles the second.
+    Every refusal here is read by CODE. The optimistic pre-check
+    (`findOwnReview`) exists and its hole is written down: the list is
+    published-only, so under pre-moderation the author's own pending review is
+    invisible to its author and the server is the one that says no.
+  - **A guest reads the reviews; only the write asks them to sign in.** Both
+    reads are anonymous (`IsAuthenticatedOrReadOnly` on the list class — GET
+    open, POST still needs an author to attribute the review to — and `AllowAny`
+    on the aggregate, both throttled from the module's own settings). So
+    `signInRequired` lives on the form bag alone, where a 401 is still the honest
+    answer, and an empty list means what it says to everybody. Nothing new became
+    visible to a guest: both endpoints were already published-only for a
+    non-moderator.
+  - **A review that is not published says so.** `pending` / `hidden` rows carry a
+    badge, a status this build does not know is named rather than rendered as an
+    ordinary review, and the submit outcome reports the created row's status so a
+    pre-moderating deployment can say "it will appear once checked".
+
+  The list envelope comes from codegen. `GET /reviews` returns core's
+  `AnchorPagination` envelope and always did, but `ReviewListCreateView`
+  instantiates its paginator inside `get()` instead of declaring a
+  `pagination_class`, so drf-spectacular used to render the response as a bare
+  array and its `anchor`/`limit`/`direction` parameters not at all.
+  stapel-reviews 0.3.0 declares both (`components/ReviewPage`, and `direction`
+  with an enum), so `ReviewPage`, `ReviewListParams` and `ReviewAnchorDirection`
+  are projections of the generated schema rather than copies this package
+  maintains.
+
+  The seller-level rating is a DISPLAY, not a fetch: reviews target the seller
+  for a specific listing, so a seller's rating is a roll-up the module cannot
+  compute (one `(target_type, target_key)` per call) and the shop composite can
+  (`shop.listing_review_summary` → `{avg, count}`, the owner's field names on
+  purpose). `<RatingBadge aggregate={…}>` renders those two numbers with no
+  request; publishing them over HTTP is the composite's job and is recorded as an
+  open gap rather than faked with an N+1 loop.
+
+  Surface: `createReviewsRuntime`/`ReviewsProvider`, three read/write hooks, the
+  pure `rating`/`list`/`refusals` readers, three headless bags, and an opt-in
+  `./default` antd skin (`ReviewsPanel`, `ReviewListPanel`, `ReviewFormCard`,
+  `RatingBadge`). en/ru/es, with the 9 module-owned error keys authored by the
+  pair because stapel-reviews ships no `translations/`. Pinned to stapel-reviews
+  0.3.0 (`>=0.3 <0.4`).
+
+  Not in scope, and not by omission: `POST {id}/moderate` and
+  `POST {id}/response` are both gated on the fail-closed `can_moderate` callback
+  and belong to a moderator console and a seller console; the reply is displayed
+  and the button to write one does not exist rather than existing switched off.
+  No nav manifest either — the pair renders inside somebody else's route.
+  `manifest.json` still lists the whole contract.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stapel contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/api/generated/schema.d.ts

@@ -11,7 +11,7 @@ export interface paths {
          *     non-moderators), or create a review.
          *
          *     ``GET`` is anonymously readable (storefront F5 verdict,
-         *     darom-storefront-design.md §13.8 note 2) — published-only filtering
+         *     the storefront spec §13.8 note 2) — published-only filtering
          *     already guarantees a guest sees nothing a moderator would need to hide.
          *     ``POST`` still requires a real identity (there is an author to attribute
          *     the review to), so the class gate is DRF's own
@@ -28,7 +28,7 @@ export interface paths {
          *     non-moderators), or create a review.
          *
          *     ``GET`` is anonymously readable (storefront F5 verdict,
-         *     darom-storefront-design.md §13.8 note 2) — published-only filtering
+         *     the storefront spec §13.8 note 2) — published-only filtering
          *     already guarantees a guest sees nothing a moderator would need to hide.
          *     ``POST`` still requires a real identity (there is an author to attribute
          *     the review to), so the class gate is DRF's own
@@ -101,7 +101,7 @@ export interface paths {
          *     for a target.
          *
          *     Anonymously readable for the same reason as the list's ``GET``
-         *     (storefront F5 verdict, darom-storefront-design.md §13.8 note 2): the
+         *     (storefront F5 verdict, the storefront spec §13.8 note 2): the
          *     aggregate is computed over published reviews only, so a guest learns
          *     nothing a moderator would need withheld.
          *
@@ -178,7 +178,7 @@ export interface components {
          *     only fires for ``GenericAPIView.pagination_class`` — never sees
          *     ``ReviewAnchorPagination``, and the envelope has to be declared by hand
          *     or spectacular renders the response as a bare array
-         *     (darom-storefront-design.md §13.8 note 3).
+         *     (the storefront spec §13.8 note 3).
          */
         ReviewPage: {
             items: components["schemas"]["ReviewResponse"][];

package/llms.txt

@@ -1,4 +1,4 @@
-# @stapel/reviews-react 0.1.0
+# @stapel/reviews-react 0.2.0
 
 Headless React flow pair for stapel-reviews (contract >=0.3 <0.4) — business + state, zero visual opinion.
 Built on @stapel/core: typed client + StapelApiError envelope, auth token refresh,

package/manifest.json

@@ -1,7 +1,7 @@
 {
   "$generated": "by scripts/gen-manifest.mjs — do not edit; drift-gated (pnpm gen:manifest:check)",
   "package": "@stapel/reviews-react",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "backend": {
     "module": "stapel-reviews",
     "contract": ">=0.3 <0.4"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@stapel/reviews-react",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Headless React pair for stapel-reviews: ratings and reviews addressed the way the module addresses them — by an opaque (target_type, target_key) pair, never by a foreign key. An anchor-paginated list a guest can read, an aggregate that renders `no reviews yet` instead of a zero-star rating when count is 0, a submit form that reads the duplicate refusal by CODE (the module answers 400, not 409) and asks for a sign-in only where the write actually needs one, and moderation states shown as they are rather than hidden. The seller-level rating is a display over the composite's projection, because reviews itself cannot roll one up. Zero visual opinion in the main entry; an opt-in /default subpath ships the antd skin.",
   "license": "MIT",
   "repository": {
@@ -44,13 +44,6 @@
     "manifest.json",
     "llms.txt"
   ],
-  "scripts": {
-    "build": "tsc -p tsconfig.json",
-    "test": "tsc -p tsconfig.test.json && vitest run --exclude test/prodBundlePurity.test.ts",
-    "test:pack": "vitest run test/prodBundlePurity.test.ts",
-    "lint": "eslint .",
-    "size": "size-limit"
-  },
   "size-limit": [
     {
       "name": "index — the headless pair (client + list window + aggregate + submit): no antd",
@@ -90,10 +83,6 @@
   },
   "devDependencies": {
     "@size-limit/preset-small-lib": "^11.2.0",
-    "@stapel/core": "workspace:^",
-    "@stapel/showcase": "workspace:^",
-    "@stapel/tokens": "workspace:^",
-    "@stapel/tokens-antd": "workspace:^",
     "@tanstack/react-query": "^5.81.0",
     "@testing-library/react": "^16.3.0",
     "@types/react": "^19.1.0",
@@ -104,12 +93,23 @@
     "react-dom": "^19.1.0",
     "size-limit": "^11.2.0",
     "typescript": "^5.8.3",
-    "vitest": "^3.2.4"
+    "vitest": "^3.2.4",
+    "@stapel/core": "^0.15.0",
+    "@stapel/showcase": "^0.2.0",
+    "@stapel/tokens": "^0.5.0",
+    "@stapel/tokens-antd": "^0.5.0"
   },
   "engines": {
     "node": ">=22"
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsc -p tsconfig.test.json && vitest run --exclude test/prodBundlePurity.test.ts",
+    "test:pack": "vitest run test/prodBundlePurity.test.ts",
+    "lint": "eslint .",
+    "size": "size-limit"
   }
-}
+}

package/src/analytics/generated/events.json

@@ -1,7 +1,7 @@
 {
   "$generated": "by scripts/gen-events.mjs — do not edit; drift-gated (pnpm gen:events:check)",
   "package": "@stapel/reviews-react",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "defined": [],
   "flows": []
 }