@odla-ai/chapter 0.56.1 → 0.57.0

package/README.md

@@ -395,6 +395,45 @@ The same renderer can also replace the placeholder chooser inside
 ```
 
 `initialState` accepts trusted server state. On a browser redirect,
+### Shared application and additional-member controls
+
+`JoinIsland` owns application readiness. Its default Submit button and the
+`disabled` value passed to `renderSubmit` reflect required controls, native
+constraints, host-provided custom validity checks, conditional fields and recipient
+prefill. Use `JoinSubmitButton` in a custom submit slot to retain the packaged
+theme and disabled styling. `submitDisabled` remains an additional host gate.
+
+Use `AdditionalMemberFields` on Apply and `payment.additionalMember` for the
+packaged editor. Supply copy, application field names and theme tokens; do not
+reimplement validation, save/error handling, or action spacing in the host.
+Declare the same conditional name/email requirements in the server application
+field contract. The quote remains authoritative for price and saved details.
+
+```tsx
+const memberOptions = {
+  copy: { label: "A membership for your mother, daughter, or sister" },
+  names: { selected: "familySelected", name: "familyName", email: "familyEmail" },
+};
+const [member, setMember] = useState({ selected: false, name: "", email: "" });
+<JoinIsland config={config} payment={{
+  initialNamedSeat: additionalMemberSelection(member) ?? undefined,
+  additionalMember: { ...memberOptions, onSaved: setMember },
+  namedSeatLabel: "Additional family member",
+}}>
+  {/* Other site application fields */}
+  <AdditionalMemberFields {...memberOptions} value={member} onChange={setMember} offer={selectedTier?.seatOffer} />
+</JoinIsland>
+```
+
+Import these controls from `@odla-ai/chapter/ui/member`. The editor uses Save
+details for both included and paid members, a separate Cancel action, retryable
+errors, and disabled controls while saving. Checkout remains read-only until
+Edit details is chosen. Legacy `renderNamedSeatEditor` remains available for
+specialized composition; new hosts should use the packaged controls.
+`JourneyFrame` supplies responsive layout and uses `--ui-accent`,
+`--ui-on-accent`, `--ui-text-muted` and `--ui-surface-2` for enabled and disabled
+states. The default checkout editor also uses these shared fields and readiness.
+
 `JoinIsland` reads the `application` capability from the query string and asks
 `GET /api/join/resume` for the canonical payment, booking, or done state; raw
 `redirect_status` and `reschedule` values never choose a UI step. Supply
@@ -1811,6 +1850,63 @@ These bite silently — a smoke test won't catch them:
   named and whether that person joined without folding the seat status machine
   itself; `NamedSeatRecipientLine` renders it.
 
+  **Decisions after the conversation (0.57.0).** Four operations close the
+  gaps a chapter hits once applicants are real people (BNF bugs fa96b11c,
+  f7bc92ee, 38000934, c3c1d338, 79590edc):
+
+  - `POST /api/admin/applications/:id/decline` refuses an applicant who holds
+    no payment: a free-tier applicant, or a paid-tier applicant who never
+    paid. The application closes as `declined` (`canceled: true`), the CRM
+    stage follows, and nothing is emailed. Under a network authority the
+    answer to "is a payment held?" comes from the authority's access record,
+    not from local provider ids, so a checkout that was started and abandoned
+    can still be declined; a held payment is refused with `payment_held` and
+    the refund is the only way to end it. A gifted seat's recipient is refused
+    with `named_seat_recipient`. `GET …/actions` offers `declined` under an
+    authority only while no checkout has reached the provider, the hub's
+    delegated stage move runs the same operation, and `RecordActions` carries
+    a Decline control beside Approve and Refund (`admin.records.decline`,
+    `admin.records.declined` copy).
+  - `POST /api/admin/applications/:id/refund` with a JSON body
+    `{ continueAs: "<free tier id>" }` is "not a paid fit": the ordinary refund,
+    then the same application moves to that free tier at the last approvable
+    stage and is approved at once, so the person keeps member access as, for
+    example, an Associate. The refunded purchase is archived in
+    `membershipCheckoutHistory`, its billing fields leave the row, and the tier
+    is checked before any money moves. Repeating the call re-approves without a
+    second refund. The response adds `continued: { tierId, status, rolePromoted,
+    emailLogged }`.
+  - The purchaser may give an invited or accepted seat to a different person
+    until it is active: `POST /api/named-seat/regift`
+    `{ recipientName, recipientEmail }` from the members page
+    (`NamedSeatPurchase` shows the control while the offer's `seat.regiftable`
+    is true), or `POST /api/admin/applications/:id/named-seat/regift` by a super
+    admin on the purchaser's behalf (`NamedSeatRecordPanel`). The authority's
+    `seat-regift` command keeps the payment and renewal line exactly as they
+    are, so an included seat works the same way; the previous invitation stops
+    resolving, a new invitation effect is queued, the former recipient is kept
+    on the seat's `formerRecipients`, and a recipient who had already accepted
+    gets a `release_named_recipient` effect that closes their application as
+    `declined` without a refund (the chapter also does this at once). Active
+    seats are final (`seat_not_regiftable`). Upgrade and re-provision the
+    network owner first: the seat gains optional `regiftedAt` and
+    `formerRecipients`, and an effect optional `recipientUserId` and
+    `recipientApplicationId`.
+  - A second-seat invitation goes out only once the buying member is approved.
+    `drainMembershipEffects` holds an `invite_named_recipient` effect while the
+    primary is `paid_pending_approval` and reports it under `held`; the
+    receiver's eligibility read says the same. The offer's `seat` carries
+    `invitationHeld: true` meanwhile, and `NamedSeatRecipientLine` says the
+    invitation is sent once the membership is approved.
+  - Anyone whose earlier applications in the chapter all ended without
+    approval (declined, refunded, canceled) may apply again from the public
+    form. The new attempt is a new application row linked to the same person:
+    it adopts the account bound to the closed attempt, takes over the unique
+    signup key, and re-stages the same CRM person; the closed row stays as
+    history. An open application still answers `account_already_exists`.
+    `resolveSignupEligibility` returns the predecessor it chose, and
+    `closedApplication` is the one definition of "ended without approval".
+
   Delivery logs distinguish sent, logged-only, in-flight, uncertain and
   retry-approved outcomes. The authenticated operator resolution route
   `/api/admin/email/log/:id/resolve` records evidence against the exact attempt;