@stapel/listings-react 0.1.0

package/dist/model/validation.js

@@ -0,0 +1,191 @@
+/**
+ * What the composer knows before it asks, and what it does with the answer.
+ *
+ * Three jobs, and the boundaries between them are the point:
+ *
+ * 1. **The mirror.** Feature values are mirrored by
+ *    `@stapel/attributes-react`'s `mirrorValidate` — the engine's own rules,
+ *    the engine's own error keys, one implementation. This module adds only
+ *    the checks that belong to LISTINGS rather than to a value type: the
+ *    description length bounds and the price shape. Nothing here is a
+ *    verdict; the server re-runs all of it.
+ *
+ * 2. **The split of the publish 400.** `POST /{pk}/publish/` answers a bad
+ *    draft with a BARE `ValidationBatchResult` — no `localizable_error`, no
+ *    envelope — so core wraps it as `stapel.http.400` with the batch sitting
+ *    on `StapelApiError.body`. A promotion that fails afterwards answers the
+ *    ordinary envelope (`error.400.publish_validation_failed`, or
+ *    `error.400.image_required` where the deployment requires a photo). Two
+ *    different 400s that mean different things; `publishRefusal` is the one
+ *    place that tells them apart.
+ *
+ * 3. **Routing a refusal onto the control that caused it.**
+ *    `featureErrorsBySlug` (attributes-react) adds the `field` param the
+ *    fleet's `useFieldError` convention routes on — the engine sends
+ *    `{feature, slug}` and never `field`. Listing-level rows (the
+ *    description, which the batch carries under the slug `"description"`)
+ *    are lifted out to their own control here.
+ *
+ * ── The mirror's ceilings are CONFIGURABLE, and that is not a nicety ───────
+ *
+ * `DESCRIPTION_MIN_LENGTH` / `DESCRIPTION_MAX_LENGTH` are `STAPEL_LISTINGS`
+ * settings a deployment moves (`conf.py`). A hardcoded 4/500 would refuse a
+ * perfectly valid submission on a host that widened them — and the server
+ * would never even hear about the refusal, so there would be nothing to
+ * appeal to. Same rule the cdn pair wrote down: **the mirror may not refuse
+ * what the server would accept.**
+ */
+import { StapelApiError, isStapelApiError } from "@stapel/core";
+import { codePointLength, featureErrorsBySlug, mirrorValidate, } from "@stapel/attributes-react";
+import { LISTINGS_I18N_KEYS } from "../i18n/keys.js";
+export const DEFAULT_DRAFT_LIMITS = {
+    descriptionMin: 4,
+    descriptionMax: 500,
+    titleMax: 255,
+    maxImages: 10,
+    requireImageOnPublish: true,
+};
+/** The slug the description's refusal is filed under — the engine files it
+ * the same way (`validate_description` returns a `FeatureValidationResult`
+ * whose slug is not a feature's), so the composer has one routing table. */
+export const DESCRIPTION_FIELD = "description";
+export const TITLE_FIELD = "title";
+export const PRICE_FIELD = "price";
+export const IMAGES_FIELD = "images";
+export const CATEGORY_FIELD = "category_id";
+/** A client-side refusal. `status: 0` on purpose: a rule this build applied
+ * must never be indistinguishable from one that came over the wire. */
+function mirrored(code, params = {}) {
+    return { code, params, status: 0, message: undefined, language: undefined };
+}
+const DECIMAL = /^\d{1,10}(?:\.\d{1,2})?$/;
+/**
+ * The listing-level half of the mirror: everything that is not a feature
+ * value. Returns refusals keyed by control, empty when nothing is wrong.
+ *
+ * Note what is NOT judged: a missing title, a missing price and a missing
+ * location. The server accepts a published listing without any of them
+ * (`publish_listing` promotes `title_draft or title` and leaves the rest),
+ * so refusing them here would block a submission the backend would take. A
+ * skin may still *encourage* them; that is copy, not a gate.
+ */
+export function mirrorListingFields(values, limits) {
+    const out = {};
+    if (values.categoryId.length === 0) {
+        out[CATEGORY_FIELD] = mirrored(LISTINGS_I18N_KEYS.composeCategoryRequired);
+    }
+    if (codePointLength(values.title) > limits.titleMax) {
+        out[TITLE_FIELD] = mirrored(LISTINGS_I18N_KEYS.composeTitleTooLong, {
+            max_length: limits.titleMax,
+        });
+    }
+    // Length in Unicode CODE POINTS, the unit Python's `len()` counts in. One
+    // emoji is one character on both sides of the wire; `String.length` would
+    // call it two and refuse a description the server accepts.
+    const described = codePointLength(values.description.trim());
+    if (described < limits.descriptionMin) {
+        out[DESCRIPTION_FIELD] = mirrored("error.400.description_too_short", {
+            min_length: limits.descriptionMin,
+            field: DESCRIPTION_FIELD,
+        });
+    }
+    else if (described > limits.descriptionMax) {
+        out[DESCRIPTION_FIELD] = mirrored("error.400.description_too_long", {
+            max_length: limits.descriptionMax,
+            field: DESCRIPTION_FIELD,
+        });
+    }
+    if (values.price.length > 0 && !DECIMAL.test(values.price)) {
+        // `validate_price_draft` refuses a negative, and the DecimalField refuses
+        // anything outside `^-?\d{0,10}(\.\d{0,2})?$`. One sentence for both:
+        // "that is not a price we can send".
+        out[PRICE_FIELD] = mirrored(LISTINGS_I18N_KEYS.composePriceInvalid);
+    }
+    if (values.images.length > limits.maxImages) {
+        out[IMAGES_FIELD] = mirrored(LISTINGS_I18N_KEYS.composeTooManyImages, {
+            max: limits.maxImages,
+        });
+    }
+    // The coordinates are a composite: half of one is not half a location.
+    const { lat, lon } = values.location;
+    const hasLat = lat !== null && lat.length > 0;
+    const hasLon = lon !== null && lon.length > 0;
+    if (hasLat !== hasLon) {
+        out["location"] = mirrored(LISTINGS_I18N_KEYS.composeGeoIncomplete);
+    }
+    return out;
+}
+/**
+ * The whole mirror: listing fields + feature values, in one routing table.
+ *
+ * Feature refusals go through `featureErrorsBySlug`, so a mirrored "too long"
+ * and a server "too long" render the SAME sentence from the SAME key — they
+ * are the same key, because the mirror speaks the engine's vocabulary.
+ */
+export function mirrorDraft(values, features, featuresDto, limits) {
+    return {
+        ...featureErrorsBySlug(mirrorValidate(features, featuresDto)),
+        ...mirrorListingFields(values, limits),
+    };
+}
+/** Is this batch clean? `valid` is the server's own summary; a caller that
+ * recomputed it from `results` could disagree with the field the API sends. */
+export function isBatchValid(batch) {
+    return batch.valid;
+}
+function isValidationBatch(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    return typeof candidate.valid === "boolean" && Array.isArray(candidate.results);
+}
+/**
+ * Split a thrown publish failure into its two meanings.
+ *
+ * The check is on the BODY, not on the status: a 400 whose body is a batch is
+ * a per-field verdict, and a 400 whose body is an envelope is a sentence. A
+ * caller that branched on `status === 400` alone would put
+ * `error.400.image_required` under a feature control.
+ */
+export function publishRefusal(thrown) {
+    if (isStapelApiError(thrown) && isValidationBatch(thrown.body)) {
+        const batch = thrown.body;
+        return {
+            kind: "invalid_draft",
+            batch,
+            fieldErrors: listingFieldErrors(batch),
+        };
+    }
+    return {
+        kind: "error",
+        error: isStapelApiError(thrown)
+            ? thrown
+            : new StapelApiError({
+                code: LISTINGS_I18N_KEYS.unknownError,
+                message: "Publishing failed",
+                status: 0,
+                body: thrown,
+            }),
+    };
+}
+/**
+ * A server batch → refusals keyed by CONTROL.
+ *
+ * One call, because the server already keys everything the way the composer
+ * does. `services.publish.validate_draft` inserts `validate_description`'s
+ * row at the FRONT of the same list, and that row's slug is literally
+ * `"description"` (`stapel_attributes/validation.py:726`) — the same key
+ * {@link DESCRIPTION_FIELD} names and the same key the mirror files its own
+ * length refusal under. So the description's control receives the server's
+ * verdict and the mirror's through one lookup, and neither can land in a
+ * page-level banner because nothing routed it.
+ */
+export function listingFieldErrors(batch) {
+    return featureErrorsBySlug(batch);
+}
+/** The rows of a batch that failed, in the order the server sent them —
+ * for a summary line above the form ("3 details need attention"). */
+export function failedResults(batch) {
+    return batch.results.filter((result) => result.status === "validation_failed");
+}
+//# sourceMappingURL=validation.js.map

package/dist/model/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/model/validation.ts"],"names":[],"mappings":"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"}

package/dist/nav/manifest.d.ts

@@ -0,0 +1,46 @@
+/**
+ * This pair's contribution to the scripted-fullstack nav contract
+ * (`@stapel/core`'s `NavEntry`/`PackageNavManifest`). `scripts/gen-nav-
+ * manifest.mjs` reads `navEntries` below, stamps `package`/`version` from THIS
+ * package's own `package.json`, and emits
+ * `packages/listings-react/nav-manifest.json` plus this package's slice of the
+ * root aggregate.
+ *
+ * ── Four entries, and the one thing they are NOT ───────────────────────────
+ *
+ * There is no entry for a card. A card is a SLOT, not a route (spec §3.7):
+ * `@stapel/search-react` takes `renderCard`, the container passes
+ * `<ListingCard>` from this pair's `/default`, and the two L2 pairs never
+ * import each other. A nav entry for it would claim a page that does not
+ * exist.
+ *
+ * `surface` is declared EXPLICITLY on all four. The derivation
+ * `requiresAuth ? "member" : "public"` lands on the same answer today, but
+ * the explicit declaration is what a public container can rely on: an entry
+ * that later gains `requiresAuth` for an unrelated reason must not silently
+ * fall out of the anonymous tree (`core/src/nav.ts`, `navEntrySurface`).
+ *
+ * ── Why the detail is public and the other three are not ───────────────────
+ *
+ * `/l/:id` is the page a shared link opens, the page a search result leads
+ * to, and the page a message quotes — a marketplace whose listing page needs
+ * a session has no shop window. It is spelled out in spec §5.2 with this
+ * exact path and this exact surface. `menuVisibleDefault: false` because a
+ * parameterized route is a navigation TARGET, not a menu item (the same
+ * treatment `auth.login` and `search.results` get).
+ *
+ * The other three need a mandate and say so. Two of them are SUBMENU entries
+ * under `account.root` — an id this pair does not own and does not declare:
+ * the cabinet has no module of its own, so the CONTAINER declares that top
+ * entry in its `stapel.nav.json` override. `resolveNav` drops an orphaned
+ * submenu entry instead of throwing (`NavPlacement.parentId`), so a host that
+ * installs this pair without a cabinet gets a smaller menu rather than a
+ * broken build.
+ */
+import type { NavEntry } from "@stapel/core";
+/** The container-owned top entry the cabinet's submenu hangs from. Declared
+ * as a constant so the two references below cannot drift apart, and exported
+ * so a container can assert it against its own override file. */
+export declare const ACCOUNT_ROOT_ID = "account.root";
+export declare const navEntries: readonly NavEntry[];
+//# sourceMappingURL=manifest.d.ts.map

package/dist/nav/manifest.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.d.ts","sourceRoot":"","sources":["../../src/nav/manifest.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE7C;;iEAEiE;AACjE,eAAO,MAAM,eAAe,iBAAiB,CAAC;AAE9C,eAAO,MAAM,UAAU,EAAE,SAAS,QAAQ,EAkDzC,CAAC"}

package/dist/nav/manifest.js

@@ -0,0 +1,56 @@
+/** The container-owned top entry the cabinet's submenu hangs from. Declared
+ * as a constant so the two references below cannot drift apart, and exported
+ * so a container can assert it against its own override file. */
+export const ACCOUNT_ROOT_ID = "account.root";
+export const navEntries = [
+    {
+        id: "listings.detail",
+        labelKey: "listings.nav.detail",
+        icon: "TagOutlined",
+        route: { path: "/l/:id" },
+        component: { export: "ListingDetailPane", subpath: "default" },
+        placement: { level: "top" },
+        menuVisibleDefault: false,
+        requiresAuth: false,
+        surface: "public",
+        order: 10,
+    },
+    {
+        id: "listings.compose",
+        labelKey: "listings.nav.compose",
+        icon: "PlusOutlined",
+        route: { path: "/new" },
+        component: { export: "ListingComposerPage", subpath: "default" },
+        placement: { level: "top" },
+        menuVisibleDefault: true,
+        requiresAuth: true,
+        surface: "member",
+        order: 20,
+    },
+    {
+        // Relative path: a child of the container's `/account` layout route.
+        id: "listings.mine",
+        labelKey: "listings.nav.mine",
+        icon: "ProfileOutlined",
+        route: { path: "listings" },
+        component: { export: "MyListingsPane", subpath: "default" },
+        placement: { level: "submenu", parentId: ACCOUNT_ROOT_ID },
+        menuVisibleDefault: true,
+        requiresAuth: true,
+        surface: "member",
+        order: 10,
+    },
+    {
+        id: "listings.favorites",
+        labelKey: "listings.nav.favorites",
+        icon: "HeartOutlined",
+        route: { path: "favorites" },
+        component: { export: "FavoritesPane", subpath: "default" },
+        placement: { level: "submenu", parentId: ACCOUNT_ROOT_ID },
+        menuVisibleDefault: true,
+        requiresAuth: true,
+        surface: "member",
+        order: 20,
+    },
+];
+//# sourceMappingURL=manifest.js.map

package/dist/nav/manifest.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest.js","sourceRoot":"","sources":["../../src/nav/manifest.ts"],"names":[],"mappings":"AAyCA;;iEAEiE;AACjE,MAAM,CAAC,MAAM,eAAe,GAAG,cAAc,CAAC;AAE9C,MAAM,CAAC,MAAM,UAAU,GAAwB;IAC7C;QACE,EAAE,EAAE,iBAAiB;QACrB,QAAQ,EAAE,qBAAqB;QAC/B,IAAI,EAAE,aAAa;QACnB,KAAK,EAAE,EAAE,IAAI,EAAE,QAAQ,EAAE;QACzB,SAAS,EAAE,EAAE,MAAM,EAAE,mBAAmB,EAAE,OAAO,EAAE,SAAS,EAAE;QAC9D,SAAS,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE;QAC3B,kBAAkB,EAAE,KAAK;QACzB,YAAY,EAAE,KAAK;QACnB,OAAO,EAAE,QAAQ;QACjB,KAAK,EAAE,EAAE;KACV;IACD;QACE,EAAE,EAAE,kBAAkB;QACtB,QAAQ,EAAE,sBAAsB;QAChC,IAAI,EAAE,cAAc;QACpB,KAAK,EAAE,EAAE,IAAI,EAAE,MAAM,EAAE;QACvB,SAAS,EAAE,EAAE,MAAM,EAAE,qBAAqB,EAAE,OAAO,EAAE,SAAS,EAAE;QAChE,SAAS,EAAE,EAAE,KAAK,EAAE,KAAK,EAAE;QAC3B,kBAAkB,EAAE,IAAI;QACxB,YAAY,EAAE,IAAI;QAClB,OAAO,EAAE,QAAQ;QACjB,KAAK,EAAE,EAAE;KACV;IACD;QACE,qEAAqE;QACrE,EAAE,EAAE,eAAe;QACnB,QAAQ,EAAE,mBAAmB;QAC7B,IAAI,EAAE,iBAAiB;QACvB,KAAK,EAAE,EAAE,IAAI,EAAE,UAAU,EAAE;QAC3B,SAAS,EAAE,EAAE,MAAM,EAAE,gBAAgB,EAAE,OAAO,EAAE,SAAS,EAAE;QAC3D,SAAS,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,eAAe,EAAE;QAC1D,kBAAkB,EAAE,IAAI;QACxB,YAAY,EAAE,IAAI;QAClB,OAAO,EAAE,QAAQ;QACjB,KAAK,EAAE,EAAE;KACV;IACD;QACE,EAAE,EAAE,oBAAoB;QACxB,QAAQ,EAAE,wBAAwB;QAClC,IAAI,EAAE,eAAe;QACrB,KAAK,EAAE,EAAE,IAAI,EAAE,WAAW,EAAE;QAC5B,SAAS,EAAE,EAAE,MAAM,EAAE,eAAe,EAAE,OAAO,EAAE,SAAS,EAAE;QAC1D,SAAS,EAAE,EAAE,KAAK,EAAE,SAAS,EAAE,QAAQ,EAAE,eAAe,EAAE;QAC1D,kBAAkB,EAAE,IAAI;QACxB,YAAY,EAAE,IAAI;QAClB,OAAO,EAAE,QAAQ;QACjB,KAAK,EAAE,EAAE;KACV;CACF,CAAC"}

package/llms.txt

@@ -0,0 +1,118 @@
+# @stapel/listings-react 0.1.0
+
+Headless React flow pair for stapel-listings (contract >=0.6 <0.7) — business + state, zero visual opinion.
+Built on @stapel/core: typed client + StapelApiError envelope, auth token refresh,
+verification-403 interception, i18n engine, analytics facade, TanStack Query layer.
+
+## The one right way (do this, the rest is a review/lint smell)
+- No raw fetch/axios. The client is injected via <ListingsProvider>/StapelConfigProvider;
+  every hook and flow already carries auth, refresh, and the error envelope.
+- Render errors, never try/catch them: a flow's state carries FlowError{code,params};
+  render `t(code, params)` and branch on `explainListingsError(code)` remediation.
+- Server state = the use* hooks (query layer); keys come only from listingsQueryKeys.
+- User strings = i18n keys (registerListingsI18n); never string literals.
+- Sign-in UI = a headless flow component; copy it (shadcn-style) to restyle.
+
+## Layers
+api (typed client) · model (hooks, session) · flows (machines) · headless · i18n
+
+## Documented flows (flows.json — canonical id, steps, endpoints)
+
+## Operations (typed; use the named op, never a path string)
+Request/response schema names are in manifest.json + the generated types.
+Paths are relative to `/listings/api/v1/`.
+- listings_api_v1_listings_archive_create: POST /listings/{id}/archive/
+- listings_api_v1_listings_complete_create: POST /listings/{id}/complete/
+- listings_api_v1_listings_create: POST /listings/
+- listings_api_v1_listings_destroy: DELETE /listings/{id}/
+- listings_api_v1_listings_favorite_create: POST /listings/{id}/favorite/
+- listings_api_v1_listings_list: GET /listings/
+- listings_api_v1_listings_my_counters_retrieve: GET /listings/my/counters/
+- listings_api_v1_listings_my_favorites_list: GET /listings/my/favorites/
+- listings_api_v1_listings_partial_update: PATCH /listings/{id}/
+- listings_api_v1_listings_publish_create: POST /listings/{id}/publish/
+- listings_api_v1_listings_retrieve: GET /listings/{id}/
+- listings_api_v1_listings_save_draft_create: POST /listings/{id}/save-draft/
+- listings_api_v1_listings_status_retrieve: GET /listings/{id}/status/
+- listings_api_v1_listings_unfavorite_create: POST /listings/{id}/unfavorite/
+- listings_api_v1_listings_update: PUT /listings/{id}/
+- listings_api_v1_listings_validate_draft_retrieve: GET /listings/{id}/validate-draft/
+
+## Query hooks (server state; keys come only from the key factory)
+- useArchiveListing (mutation) → archive
+- useCompleteListing (mutation) → complete
+- useCreateDraft (mutation) → createDraft
+- useDeleteListing (mutation) → remove
+- useFavoriteListing (mutation) → favorite+unfavorite
+- useListing (query) → retrieve
+- useListingCards (query) → list
+- useListingStatus (query) → status
+- useMyCounters (query) → myCounters
+- useMyFavorites (query) → myFavorites
+- usePublishListing (mutation) → publish
+- useSaveDraft (mutation) → saveDraft
+- useValidateDraft (query) → validateDraft
+
+## Errors (render t(code, params); UX from remediation)
+63 keys (full catalog: manifest.json §errors). By remediation: fix_input 35 · retry 15 · verify 5 · wait_and_retry 5 · contact_support 2 · reauthenticate 1.
+Param-bearing keys (interpolation slots matter):
+- error.400.description_too_long [400] → fix_input {max_length}
+- error.400.description_too_short [400] → fix_input {min_length}
+- error.400.feature_above_maximum [400] → fix_input {feature}
+- error.400.feature_below_minimum [400] → fix_input {feature}
+- error.400.feature_invalid_config [400] → fix_input {feature}
+- error.400.feature_invalid_format [400] → fix_input {feature}
+- error.400.feature_invalid_type [400] → fix_input {feature}
+- error.400.feature_mandatory_missing [400] → fix_input {feature}
+- error.400.feature_not_allowed [400] → fix_input {feature}
+- error.400.feature_not_in_options [400] → fix_input {feature}
+- error.400.feature_unknown [400] → fix_input {feature}
+- error.400.feature_unknown_type [400] → fix_input {feature}
+- error.400.field.blank [400] → fix_input {field}
+- error.400.field.does_not_exist [400] → fix_input {field}
+- error.400.field.invalid [400] → fix_input {field}
+- error.400.field.invalid_choice [400] → fix_input {field}
+- error.400.field.max_length [400] → fix_input {field,max_length}
+- error.400.field.max_value [400] → fix_input {field,max_value}
+- error.400.field.min_length [400] → fix_input {field,min_length}
+- error.400.field.min_value [400] → fix_input {field,min_value}
+- error.400.field.null [400] → fix_input {field}
+- error.400.field.required [400] → fix_input {field}
+- error.400.field.unique [400] → fix_input {field}
+- error.400.listing_feature_not_allowed [400] → fix_input {feature}
+- error.409.invalid_listing_transition [409] → fix_input {from_status}
+- error.429.rate_limit [429] → wait_and_retry {retry_after_minutes}
+
+## Analytics events (typed; defineEvent → events.json, drift-gated)
+- (no app defineEvent() in this pair — its analytic events are the
+  auto-instrumented flow funnels below)
+
+## Flow funnels (auto-instrumented: flow.<id>.<step> {phase})
+
+```tsx
+// Typed event + tracked() click (the one right way; §3.1).
+const planSelected = defineEvent({
+  name: "pricing.plan.selected",
+  description: "User picked a plan",
+  props: { plan: prop.oneOf(["free", "pro", "team"], "Plan code") },
+});
+const { tracked } = useTracked();
+<Button onClick={tracked(planSelected, { plan }, startCheckout)} />
+// A click that STEPS a flow machine is already instrumented — mark it
+// data-analytics="flow" instead; tracked() on top double-counts (§3.2).
+```
+
+## Demos (defineDemo → manifest.demos; compiled, linted, rendered examples)
+- listings.card → <ListingCard> [default|visitor]  demo/ListingCard.demo.tsx
+- listings.composer → <ListingComposerPage> [default|photos-in-flight|unsupported-type]  demo/ListingComposer.demo.tsx
+- listings.detail → <ListingDetailPane> [default|owner]  demo/ListingDetail.demo.tsx
+- listings.favorites → <FavoritesPane> [default|empty|failed|visitor]  demo/Favorites.demo.tsx
+- listings.mine → <MyListingsPane> [default|no-source]  demo/MyListings.demo.tsx
+Each source file is the canonical usage snippet (open the default variant).
+
+## Snippets
+```tsx
+// Error rendering + remediation branch (one pattern for every pair).
+const r = explainListingsError(err.code); // 'wait_and_retry' | 'verify' | ...
+return <Alert action={r}>{t(err.code, err.params)}</Alert>;
+```