orionplace-react 0.7.7 → 0.8.0

package/templates/components/orionplace/cart/CartItemOptions.README.md

@@ -1,172 +0,0 @@
-# CartItemOptions · React
-
-## English
-
-Product, text and file options for one cart item.
-
-## Contract and dependencies
-
-`group.option_type.option_type` selects the body: `text` and `textarea` show a
-text field, `file` shows an upload field, and other values show option products.
-The localized `group.option_name` labels the disclosure. A required group stays
-marked as needed until the cart response contains nonblank text, a saved file or
-a product option with a positive quantity. Opening and closing the disclosure
-does not change the cart.
-
-Option products use compact `ProductCard` components without ordinary purchase
-or wishlist actions. Products returned inside the group are registered in the
-isolated product store and also supplied during SSR, so names, images, prices
-and available variants render before hydration. Variants outside the group stay
-disabled. `onRequestSecondaryVariants` forwards a secondary-variant lookup.
-
-Add sends quantity `1`; plus and minus change it by one; minus at `1` sends
-`0`. `onChange` receives `cart_customer_option_first_set`, the new `quantity`
-and `params.delivery_option_item_id = group.options[].id`. The maximum is the
-smallest available stock and positive group limit. A zero group limit means the
-group does not apply that limit. The refreshed `group` remains the source of
-displayed quantity and total.
-
-Text and file Save calls `cart_customer_option_add_additional` with a `FormData`
-body and `params.option_group_id = group.id`. Text is stored in the JSON `data`
-part. A selected file is stored as `option_file_data`, while `data` contains an
-empty object. Clear calls `cart_customer_option_cleanup_additional`. Rejected
-actions preserve the draft and show the error. Unsaved text survives unrelated
-`group` updates; a later refreshed saved value replaces it after a successful
-action. A successful upload clears the native file input.
-
-The upload limit `limits.file_max_mb` (domain setting `cart_option_file_max_mb`, default `10`, `0` means no limit) is shown under the field as “Up to N MB”; a larger chosen file shows “The file is larger than N MB.” and Save stays disabled. The backend checks the same limit and answers a larger file with the `option_file_data` field error “File … is too large. Maximum size is N MB.”, shown like other cart errors.
-
-`disabled` and `pending` block every control. `error` displays a parent request
-error. A rejected action is shown in the group unless `showRequestErrors` is
-`false`, as inside `StorefrontCart`, which shows it once above the lines. Source is maintained in
-`components/orionplace/cart/CartItemOptions.tsx`; the physical interface is
-`interfaces/orionplace/cart/ICartData.ts`.
-
-### Props
-
-| Prop                                                                              | Meaning                                                                                            |
-| --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
-| `group: ICartOptionGroup`                                                         | Option group belonging to the current cart item.                                                   |
-| `disabled?: boolean`                                                              | Disables the component controls and prevents new actions.                                          |
-| `pending?: boolean`                                                               | Shows the loading state and blocks duplicate actions.                                              |
-| `error?: string`                                                                  | Customer-visible error for the component request; omit it when no request failed.                  |
-| `showRequestErrors?: boolean`                                                     | Shows a rejected action inside the component (default `true`). `StorefrontCart` passes `false`: it shows the error above the lines.|
-| `productHref?: (productId: number) => string`                                     | The page of an offered product: its picture and name link there. `CartLineItem` passes its own `productHref`.|
-| `onChange?: (action: CartItemOptionAction) => Promise<unknown> \| unknown`        | Called when the visitor confirms a new value. The callback payload is shown in its type.           |
-| `onRequestSecondaryVariants?: (request: IProductSecondaryVariantRequest) => void` | Passes the product ID in `product`, product group ID in `productGroup` and primary variant in `variant` when its secondary variants need loading. The application loads them and supplies them to the product store. |
-
-## Русский
-
-Компонент показывает варианты товара, текст или файл для одной позиции
-корзины.
-
-`group.option_type.option_type` определяет содержимое: `text` и `textarea`
-показывают текстовое поле, `file` — выбор файла, остальные значения — товары,
-которые можно добавить как опции. Заголовок берётся из локализованного
-`group.option_name`. Обязательная группа остаётся отмеченной как незаполненная,
-пока ответ корзины не содержит непустой текст, сохранённый файл или товарную
-опцию с количеством больше нуля. Открытие и закрытие блока не меняет корзину.
-
-Товарные опции используют компактный `ProductCard` без обычных действий покупки
-и избранного. Полученные внутри группы товары добавляются в отдельный store
-товаров и передаются карточке для SSR, поэтому имя, изображение, цена и доступные
-варианты видны до гидратации. Варианты, которых нет в группе, отключены.
-`onRequestSecondaryVariants` передаёт запрос дополнительных вариантов.
-
-«Добавить» отправляет количество `1`, плюс и минус меняют его на единицу, а
-минус при значении `1` отправляет `0`. `onChange` получает
-`cart_customer_option_first_set`, новое `quantity` и
-`params.delivery_option_item_id = group.options[].id`. Максимум равен
-наименьшему из доступного остатка и положительных ограничений группы. Нулевое
-ограничение группы означает, что это ограничение не применяется. Показанное
-количество и сумма всегда берутся из обновлённого `group`.
-
-Сохранение текста или файла вызывает
-`cart_customer_option_add_additional` с `FormData` и
-`params.option_group_id = group.id`. Текст находится в JSON-части `data`. Файл
-передаётся как `option_file_data`, а `data` содержит пустой объект. Очистка
-вызывает `cart_customer_option_cleanup_additional`. При отклонённом действии
-черновик сохраняется и показывается ошибка. Несохранённый текст не теряется при
-постороннем обновлении `group`; после успешного действия новое сохранённое
-значение из ответа заменяет его. Успешная загрузка очищает поле файла.
-
-Предел загрузки: `limits.file_max_mb` (настройка домена `cart_option_file_max_mb`, по умолчанию `10`, `0` — без ограничения) выводится под полем как «До N МБ»; для выбранного файла больше этого размера показывается «Файл больше N МБ.», и кнопка сохранения недоступна. Бэкенд проверяет тот же предел и отвечает на больший файл ошибкой поля `option_file_data` «File … is too large. Maximum size is N MB.» (в переводе домена), которая показывается как другие ошибки корзины.
-
-`disabled` и `pending` блокируют все элементы. `error` показывает ошибку
-родительского запроса. Ошибка отклонённого действия выводится в группе, если
-`showRequestErrors` не `false`; внутри `StorefrontCart` она показывается один
-раз над товарами. Исходный файл:
-`components/orionplace/cart/CartItemOptions.tsx`; физический интерфейс:
-`interfaces/orionplace/cart/ICartData.ts`.
-
-### Свойства
-
-| Свойство                                                                          | Назначение                                                                                               |
-| --------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| `group: ICartOptionGroup`                                                         | Группа дополнений текущей позиции корзины.                                                               |
-| `disabled?: boolean`                                                              | Блокирует элементы компонента и новые действия.                                                          |
-| `pending?: boolean`                                                               | Показывает загрузку и блокирует повторные действия.                                                      |
-| `error?: string`                                                                  | Ошибка запроса для покупателя; не передавайте её, если запрос не завершился ошибкой.                     |
-| `showRequestErrors?: boolean`                                                     | Показывать ошибку отклонённого действия в самом компоненте (по умолчанию `true`). `StorefrontCart` передаёт `false`: ошибку он показывает над товарами.|
-| `productHref?: (productId: number) => string`                                     | Страница предлагаемого товара: на неё ведут его фото и название. `CartLineItem` передаёт свой `productHref`.|
-| `onChange?: (action: CartItemOptionAction) => Promise<unknown> \| unknown`        | Вызывается, когда покупатель подтверждает новое значение. Данные обработчика указаны в его типе.         |
-| `onRequestSecondaryVariants?: (request: IProductSecondaryVariantRequest) => void` | Передаёт ID товара в `product`, ID группы товаров в `productGroup` и основной вариант в `variant`, когда для него нужно загрузить дополнительные варианты. Приложение загружает и передаёт их в хранилище товаров. |
-## Response fields and application actions
-
-The following tables describe the response and the supplied composition’s follow-up actions. The framework-specific props and events above identify which work belongs to the component and which belongs to its parent.
-
-### English
-
-### Selected quantity and available stock
-
-`group.options[]` — Each row is a cart option record. A save sends the new total quantity. The maximum is the smallest stock/per-record/same-product bound, rounded down and never below zero; the refreshed cart confirms quantity and price.
-
-| Field or condition | Meaning and application action |
-| --- | --- |
-| `group.id` / `options[].id` / `options[].product.id` | The group ID identifies text/file save and cleanup. The option record ID is `delivery_option_item_id` for `cart_customer_option_first_set`. The product ID identifies the product displayed in that option. |
-| `quantity` + `quantity_left` | Selected units plus units still available after the cart’s other uses of the same product. This sum is the stock bound for the new quantity. Negative remaining stock can reduce the bound below the current selection. |
-| `limits.c_max_product_quantity_in_group` | Caps the new quantity of this option record. Zero leaves this limit unconfigured. |
-| `limits.c_max_products_quantity_for_group` | When saving an option, this cap counts the same product across records in the group; subtract other records with the same product.id. At order creation it also caps the sum of all selected product-option quantities in the group. Zero disables the cap. |
-| Quantity example | With 2 selected and 3 left, stock permits a new total of 5. A per-record limit of 4 reduces it to 4. A same-product limit of 5 with 2 in another record reduces it to 3. Saving sends `quantity: 3`. |
-| `quantity: 0` | Deselects the option. A positive selection with `multiple_choices: false` deselects the other options in this group. Reload the cart after confirmation. |
-| Missing `options` or `product: null` | No product card is available for that record. A missing list is handled as empty; keep any saved text/file state. |
-
-### Saved text, files and required groups
-
-`group` — The returned values describe the saved choice. Editing a local field does not complete a required group until the save is confirmed.
-
-| Field or condition | Meaning and application action |
-| --- | --- |
-| `option_type.option_type`: `text` / `textarea` | Send multipart `data` containing `option_text_data` to `cart_customer_option_add_additional`, with `option_group_id: group.id`. The returned text must remain nonempty after trimming for a required text group to be complete. |
-| `option_type.option_type`: `file` | Send the file in multipart `option_file_data`, plus an empty JSON object in `data`, using the same group endpoint. `option_file_data` in the cart response is the saved basename; an empty string means no saved file. Save stays disabled until a new file is chosen; without one the saved file is kept. |
-| `option_group_required` | True marks the group as required. Text needs nonblank saved text, a file needs a saved filename, and a product group needs an option with positive quantity. |
-| Cleanup | `cart_customer_option_cleanup_additional` takes `option_group_id: group.id` and clears the saved text/file. A failed save preserves the local input; a confirmed save reloads the cart. |
-
-### Русский
-
-### Выбранное количество и остаток
-
-`group.options[]` — Каждая позиция — запись опции корзины. Сохраняется новое полное количество. Максимум — наименьший предел запаса, записи и одного товара, округлённый вниз и не ниже нуля; обновлённая корзина подтверждает количество и цену.
-
-| Поле или условие | Значение и действие приложения |
-| --- | --- |
-| `group.id` / `options[].id` / `options[].product.id` | ID группы используется для сохранения и очистки текста/файла. ID записи опции передаётся как `delivery_option_item_id` в `cart_customer_option_first_set`. ID товара определяет товар в карточке опции. |
-| `quantity` + `quantity_left` | Выбранные единицы плюс доступный остаток с учётом других использований этого товара в корзине. Сумма ограничивает новое количество. Отрицательный остаток может уменьшить предел ниже текущего выбора. |
-| `limits.c_max_product_quantity_in_group` | Предел нового количества в этой записи опции. Ноль означает, что это ограничение не задано. |
-| `limits.c_max_products_quantity_for_group` | При сохранении опции предел учитывает один товар во всех записях группы; вычтите другие записи с тем же product.id. При создании заказа он также ограничивает сумму количеств всех выбранных товарных опций группы. Ноль отключает предел. |
-| Пример количества | Выбрано 2, осталось 3: запас допускает новое количество 5. Предел записи 4 снижает его до 4. Предел одного товара 5 при количестве 2 в другой записи снижает его до 3. Запрос сохранения передаёт `quantity: 3`. |
-| `quantity: 0` | Снимает выбор опции. При `multiple_choices: false` положительное количество снимает выбор остальных опций группы. После подтверждения загрузите корзину заново. |
-| Нет `options` или `product: null` | Для такой записи карточка товара недоступна. Отсутствующий список обрабатывается как пустой; сохранённые текст и файл продолжают учитываться. |
-
-### Сохранённые текст, файл и обязательность
-
-`group` — Поля ответа описывают сохранённый выбор. Ввод в локальное поле заполняет обязательную группу после подтверждённого сохранения.
-
-| Поле или условие | Значение и действие приложения |
-| --- | --- |
-| `option_type.option_type`: `text` / `textarea` | Передайте multipart-поле `data` с `option_text_data` в `cart_customer_option_add_additional`, указав `option_group_id: group.id`. Обязательная текстовая группа заполнена, когда сохранённый текст непустой после удаления пробелов по краям. |
-| `option_type.option_type`: `file` | Передайте файл в multipart-поле `option_file_data` и пустой JSON-объект в `data` в тот же метод группы. `option_file_data` в ответе корзины — имя сохранённого файла; пустая строка означает, что файла нет. Кнопка сохранения недоступна, пока не выбран новый файл; без него сохранённый файл остаётся. |
-| `option_group_required` | True помечает группу обязательной. Для текста нужен непустой сохранённый текст, для файла — сохранённое имя, для товарной группы — опция с положительным количеством. |
-| Очистка | `cart_customer_option_cleanup_additional` получает `option_group_id: group.id` и очищает сохранённые текст/файл. Ошибка сохранения сохраняет локальный ввод; подтверждённое сохранение обновляет корзину. |
-
-[English guide](https://orionmarket.place/en/sandbox/components/react/cart-item-options) · [Русский](https://orionmarket.place/ru/sandbox/components/react/cart-item-options)

package/templates/components/orionplace/cart/CartItemOptions.module.css

@@ -1,113 +0,0 @@
-.root { box-sizing: border-box; min-width: 0; color: var(--orionplace-text); }
-.root[data-option-state='missing'] { padding-left: 0.75rem; border-left: 2px solid var(--orionplace-attention); }
-.root > summary { display: flex; align-items: center; gap: 0.75rem; padding: 0.75rem 0; cursor: pointer; list-style: none; font-size: 0.75rem; line-height: calc(1 / 0.75); font-weight: 500; text-transform: uppercase; letter-spacing: 0.08em; outline: none; }
-.root > summary::-webkit-details-marker { display: none; }
-.root > summary:focus-visible { opacity: 0.7; }
-@media (hover: hover) {
-  .root > summary:hover {
-    opacity: 0.7;
-  }
-}
-.root > summary::after { content: '+'; width: 1rem; flex: 0 0 auto; font-size: 1rem; font-weight: 400; line-height: 1; text-align: center; }
-.root[open] > summary::after { content: '\2212'; }
-.title { display: flex; min-width: 0; flex: 1; flex-wrap: wrap; align-items: baseline; gap: 0.25rem 0.75rem; }
-.name { display: inline-flex; align-items: baseline; gap: 0.25rem; }
-.hint { color: var(--orionplace-muted); font-weight: 400; }
-.missing { color: var(--orionplace-attention); font-weight: 400; text-transform: none; letter-spacing: normal; }
-.required { display: inline-flex; min-width: 6.5rem; flex: 0 0 auto; align-items: center; justify-content: center; gap: 0.25rem; padding: 0.125rem 0.5rem; border: 1px solid var(--orionplace-border); color: var(--orionplace-muted); background: var(--orionplace-muted-surface); font-size: 0.625rem; line-height: 1rem; }
-.required[data-state='missing'] { border-color: var(--orionplace-attention); color: var(--orionplace-attention); background: var(--orionplace-attention-surface); }
-.required svg { width: 0.75rem; height: 0.75rem; fill: none; stroke: currentColor; stroke-width: 2; stroke-linecap: round; stroke-linejoin: round; }
-.form,
-.controls { display: flex; min-width: 0; flex-direction: column; gap: 0.75rem; padding-bottom: 1rem; }
-.field { display: flex; min-width: 0; flex-direction: column; gap: 0.5rem; color: var(--orionplace-muted); font-size: 0.75rem; line-height: calc(1 / 0.75); text-transform: uppercase; letter-spacing: 0.08em; }
-.field textarea,
-.field input { box-sizing: border-box; width: 100%; min-width: 0; min-height: 2.75rem; padding: 0.65rem 0.75rem; border: 1px solid var(--orionplace-border); border-radius: 0; color: var(--orionplace-text); background: var(--orionplace-surface); font: inherit; font-size: 0.875rem; text-transform: none; letter-spacing: normal; outline: none; }
-.field textarea { min-height: 7rem; resize: vertical; line-height: 1.5; }
-.field b { color: var(--orionplace-danger); font-weight: 400; }
-.actions { display: flex; flex-wrap: wrap; gap: 0.75rem; }
-.button,
-.add { box-sizing: border-box; display: inline-flex; width: fit-content; min-height: 2.75rem; align-items: center; justify-content: center; padding: 0.65rem 1.25rem; border: 1px solid var(--orionplace-text); border-radius: 0; color: var(--orionplace-text); background: transparent; font: inherit; font-size: 0.75rem; line-height: calc(1 / 0.75); font-weight: 500; text-transform: uppercase; letter-spacing: 0.08em; cursor: pointer; }
-.button:disabled,
-.add:disabled,
-.quantity button:disabled { cursor: not-allowed; opacity: 0.4; }
-.primary,
-.add { border-color: var(--orionplace-accent); color: var(--orionplace-surface); background: var(--orionplace-accent); }
-.button:focus-visible { background: var(--orionplace-hover); outline: none; }
-.primary:focus-visible,
-.add:focus-visible { background: var(--orionplace-accent); opacity: 0.85; }
-@media (hover: hover) {
-  .button:hover { background: var(--orionplace-hover); }
-  .primary:hover,
-  .add:hover { background: var(--orionplace-accent); opacity: 0.85; }
-}
-.cards { display: grid; min-width: 0; gap: 1.5rem; margin: 0; padding: 0 0 1.25rem; list-style: none; }
-.cards > li { min-width: 0; }
-
-/*
- * An option is a smaller line under its product than a catalogue tile:
- * the shipment above already names the store it is ordered from. `> li`
- * outranks the card's own compact rules whatever order the styles load in.
- */
-.cards > li :global([data-product-layout='compact']) {
-  /* Not a measuring box: the option keeps this line at any width. */
-  container-type: normal;
-  grid-template-columns: 4rem minmax(0, 1fr);
-  column-gap: 1rem;
-  row-gap: 0.5rem;
-}
-/* The image keeps its own column beside the name, price and choices. */
-.cards > li :global([data-product-layout='compact'] > *) {
-  grid-column: 2;
-}
-.cards > li :global([data-product-layout='compact'] > [data-product-image]) {
-  grid-column: 1;
-  grid-row: span 3;
-}
-.cards > li :global([data-product-part='ProductCardSeller']) {
-  display: none;
-}
-.cards > li :global([data-product-image]) {
-  max-width: 4rem;
-}
-.cards > li :global([data-product-image] img),
-.cards > li :global([data-product-image] [data-image-placeholder]) {
-  height: 4rem;
-}
-.cards > li :global([data-product-part='ProductCardTitle']),
-.cards > li :global([data-product-part='ProductCardPrice'] span),
-.cards > li :global([data-product-part='ProductCardPrice'] del) {
-  font-size: 0.8125rem;
-  line-height: 1.125rem;
-}
-/* From 592px of the cart's own width, as the cart's other steps. */
-@container (width >= 592px) {
-  .cards > li :global([data-product-layout='compact']) {
-    grid-template-columns: 4.5rem minmax(0, 1fr);
-  }
-  .cards > li :global([data-product-image]) {
-    max-width: 4.5rem;
-  }
-  .cards > li :global([data-product-image] img),
-  .cards > li :global([data-product-image] [data-image-placeholder]) {
-    height: 4.5rem;
-  }
-}
-.controls { gap: 0.5rem; padding: 0; }
-.quantity { display: flex; width: fit-content; height: 2.25rem; align-items: stretch; overflow: hidden; border: 1px solid var(--orionplace-text); background: var(--orionplace-surface); }
-.quantity button { display: grid; width: 2.25rem; place-items: center; border: 0; color: inherit; background: transparent; font: inherit; font-size: 1rem; line-height: 1.5; cursor: pointer; }
-.quantity button:focus-visible { background: var(--orionplace-hover); outline: none; }
-@media (hover: hover) {
-  .quantity button:hover {
-    background: var(--orionplace-hover);
-    outline: none;
-  }
-}
-.quantity span { display: grid; min-width: 2.25rem; place-items: center; border: 0 solid var(--orionplace-border); border-right-width: 1px; border-left-width: 1px; font-size: 0.875rem; line-height: calc(1.25 / 0.875); font-weight: 500; }
-.add { min-width: 6rem; min-height: 2.25rem; padding: 0.4rem 1.25rem; }
-.note,
-.total,
-.error { margin: 0; font-size: 0.75rem; line-height: 1.5; }
-.note { color: var(--orionplace-muted); }
-.total { font-size: 0.875rem; font-weight: 500; }
-.error { margin-bottom: 1rem; padding: 0.75rem; border: 1px solid var(--orionplace-danger); color: var(--orionplace-danger); }
-