@xsolla/xui-b2b-itemer-group 0.216.0 → 0.217.0

package/native/index.d.mts

@@ -3,33 +3,134 @@ import React__default, { ReactNode } from 'react';
 import { ThemeOverrideProps } from '@xsolla/xui-core';
 import { BaseIconComponent } from '@xsolla/xui-icons-base';
 
-/** Any `@xsolla/xui-icons-base` icon component for row remove buttons. Defaults to `Remove`. */
+/** Any `@xsolla/xui-icons-base` icon component for row remove buttons. */
 type ItemerGroupRemoveIcon = BaseIconComponent;
-type ItemerGroupContentType = "input" | "select";
+/**
+ * Built-in remove-button icons. Either option works with any variant of the
+ * component — it is not tied to the kind of control used in the rows.
+ *
+ * `cross` renders `Remove` (×), `minus` renders `Minus` (−).
+ */
+type ItemerGroupRemoveButtonIcon = "cross" | "minus";
+/**
+ * Width of a single control column inside a row.
+ *
+ * - `number` — flex grow factor. `1` is an equal share, `2` is twice as wide
+ *   as a sibling column with `1`.
+ * - `"auto"` — the column takes its control's own width and never grows or
+ *   shrinks. Use it for fixed-size controls such as `ItemerGroupPreview`.
+ * - any other `string` — an explicit CSS length used as `flex-basis`,
+ *   typically a percentage (e.g. `"40%"`).
+ */
+type ItemerGroupColumnWidth = number | "auto" | string;
 interface ItemerGroupProps extends ThemeOverrideProps {
     label?: string | string[];
+    /**
+     * Toggle the label row. Works for every variant of the component, so a
+     * label can be defined and hidden without dropping the `label` prop.
+     */
+    showLabel?: boolean;
     children?: ReactNode;
     draggable?: boolean;
     /**
-     * Row control layout — sets the default remove icon when `removeIcon` is omitted.
-     * `input` uses `Remove` (×); `select` uses `Minus` (−).
+     * Minimum number of rows the group must keep. Remove buttons are hidden
+     * while the row count is at or below this value.
+     *
+     * - `1` (default) — the last remaining row cannot be removed.
+     * - `0` — every row can be removed, so the list may become empty. Use this
+     *   when having no items is a valid state.
      */
-    contentType?: ItemerGroupContentType;
+    minRows?: number;
     /**
-     * Icon component for row remove buttons — any export from `@xsolla/xui-icons-base`
-     * (e.g. `Remove`, `Minus`). Overrides the `contentType` default.
+     * Maximum number of rows the group accepts. Once the row count reaches this
+     * value the whole action row below the list — the built-in add button *and*
+     * any `actions`, such as an "Upload file" button — is hidden, so no further
+     * item can be added.
+     *
+     * Omit for an unbounded list (the default).
+     */
+    maxRows?: number;
+    /**
+     * Which built-in icon the row remove buttons use. Independent of the kind of
+     * control rendered in the rows.
+     */
+    removeButtonIcon?: ItemerGroupRemoveButtonIcon;
+    /**
+     * Escape hatch for an arbitrary icon component from `@xsolla/xui-icons-base`.
+     * Overrides `removeButtonIcon`.
      */
     removeIcon?: ItemerGroupRemoveIcon;
+    /**
+     * Width of each control column, applied to both the label row and every
+     * `ItemerGroupRow`. Omit for equal-width columns.
+     *
+     * Columns beyond the end of the array fall back to an equal share.
+     */
+    columnWidths?: ItemerGroupColumnWidth[];
     onAdd?: () => void;
     addButtonLabel?: string;
     showAddButton?: boolean;
+    /**
+     * Extra action buttons rendered in the row below the list, after the
+     * built-in add button — for example an "Upload file" `Button` that opens a
+     * file picker. The row is rendered when either the add button or `actions`
+     * is present, so `showAddButton={false}` + `actions` gives an upload-only
+     * variant.
+     *
+     * Hidden together with the add button once `maxRows` is reached.
+     */
+    actions?: ReactNode;
+    className?: string;
+    testID?: string;
+}
+interface ItemerGroupFileCellProps extends ThemeOverrideProps {
+    /** File name (or any primary text). Truncated with an ellipsis. */
+    name: string;
+    /** Secondary text shown on the right, typically the file size (`"1.5MB"`). */
+    meta?: string;
+    /**
+     * Highlights the cell as invalid without rendering a message. Use it when
+     * the validation text lives elsewhere on the page.
+     */
+    error?: boolean;
+    /**
+     * Validation message rendered below the cell — for example when an uploaded
+     * file is too large. Implies `error`, so it does not have to be set as well.
+     */
+    errorMessage?: string;
+    className?: string;
+    testID?: string;
+}
+interface ItemerGroupPreviewProps extends ThemeOverrideProps {
+    /**
+     * Image URL. When omitted the preview renders a neutral placeholder with a
+     * file icon.
+     */
+    src?: string;
+    alt?: string;
+    /**
+     * Renders a spinner in place of the image or the file-icon placeholder while
+     * the thumbnail is being resolved — for example while fetching the preview
+     * of a link the user has just pasted. Takes precedence over `src`.
+     */
+    loading?: boolean;
+    /** Accessible label announced while `loading` is set. */
+    loadingLabel?: string;
     className?: string;
     testID?: string;
 }
 interface ItemerGroupRowProps {
+    /**
+     * Row content. Any control is allowed — `Input` and `Select` are the common
+     * cases, but a date picker or anything else works too. Each direct child
+     * becomes one column, sized by the parent's `columnWidths`.
+     */
     children: ReactNode;
+    /**
+     * Removes this row. The button is hidden automatically while this is the
+     * last remaining row of the group.
+     */
     onRemove?: () => void;
-    onAdd?: () => void;
     className?: string;
 }
 
@@ -37,11 +138,46 @@ declare const ItemerGroup: React__default.FC<ItemerGroupProps>;
 
 declare const ItemerGroupRow: React__default.FC<ItemerGroupRowProps>;
 
+/**
+ * Read-only row content for an uploaded file — the file name on the left and
+ * an optional meta text (typically the size) on the right, styled like a
+ * `size="sm"` input so it lines up with other controls in the group.
+ *
+ * The cell is non-interactive by design: the user cannot edit the file name
+ * despite the input-like chrome. Pass `errorMessage` to surface file-level
+ * validation (e.g. "file is too large") below the cell, matching how `Input`
+ * renders its own errors.
+ *
+ * Pair it with `ItemerGroupPreview` for a thumbnail column and with the group's
+ * `actions` slot for an "Upload file" button.
+ */
+declare const ItemerGroupFileCell: React__default.FC<ItemerGroupFileCellProps>;
+
+/**
+ * Fixed-size 77×40 thumbnail for a file row. Renders, in order of precedence:
+ * a spinner while `loading`, the image when `src` is set, and a neutral
+ * placeholder with a file icon otherwise.
+ *
+ * Because the size is fixed, give its column `"auto"` in the parent group's
+ * `columnWidths` (e.g. `columnWidths={["auto", 1]}`) so it does not stretch.
+ */
+declare const ItemerGroupPreview: React__default.FC<ItemerGroupPreviewProps>;
+
 interface ItemerGroupContextValue {
     draggable: boolean;
+    /**
+     * Number of rows in the group. `0` means the row is rendered outside an
+     * `ItemerGroup`, so the row count is unknown.
+     */
     rowCount: number;
+    /**
+     * Minimum number of rows the group keeps. Remove buttons are hidden while
+     * `rowCount <= minRows`.
+     */
+    minRows: number;
     removeIcon: ItemerGroupRemoveIcon;
+    columnWidths?: ItemerGroupColumnWidth[];
 }
 declare const ItemerGroupContext: React.Context<ItemerGroupContextValue>;
 
-export { ItemerGroup, type ItemerGroupContentType, ItemerGroupContext, type ItemerGroupProps, type ItemerGroupRemoveIcon, ItemerGroupRow, type ItemerGroupRowProps };
+export { ItemerGroup, type ItemerGroupColumnWidth, ItemerGroupContext, ItemerGroupFileCell, type ItemerGroupFileCellProps, ItemerGroupPreview, type ItemerGroupPreviewProps, type ItemerGroupProps, type ItemerGroupRemoveButtonIcon, type ItemerGroupRemoveIcon, ItemerGroupRow, type ItemerGroupRowProps };

package/native/index.d.ts

@@ -3,33 +3,134 @@ import React__default, { ReactNode } from 'react';
 import { ThemeOverrideProps } from '@xsolla/xui-core';
 import { BaseIconComponent } from '@xsolla/xui-icons-base';
 
-/** Any `@xsolla/xui-icons-base` icon component for row remove buttons. Defaults to `Remove`. */
+/** Any `@xsolla/xui-icons-base` icon component for row remove buttons. */
 type ItemerGroupRemoveIcon = BaseIconComponent;
-type ItemerGroupContentType = "input" | "select";
+/**
+ * Built-in remove-button icons. Either option works with any variant of the
+ * component — it is not tied to the kind of control used in the rows.
+ *
+ * `cross` renders `Remove` (×), `minus` renders `Minus` (−).
+ */
+type ItemerGroupRemoveButtonIcon = "cross" | "minus";
+/**
+ * Width of a single control column inside a row.
+ *
+ * - `number` — flex grow factor. `1` is an equal share, `2` is twice as wide
+ *   as a sibling column with `1`.
+ * - `"auto"` — the column takes its control's own width and never grows or
+ *   shrinks. Use it for fixed-size controls such as `ItemerGroupPreview`.
+ * - any other `string` — an explicit CSS length used as `flex-basis`,
+ *   typically a percentage (e.g. `"40%"`).
+ */
+type ItemerGroupColumnWidth = number | "auto" | string;
 interface ItemerGroupProps extends ThemeOverrideProps {
     label?: string | string[];
+    /**
+     * Toggle the label row. Works for every variant of the component, so a
+     * label can be defined and hidden without dropping the `label` prop.
+     */
+    showLabel?: boolean;
     children?: ReactNode;
     draggable?: boolean;
     /**
-     * Row control layout — sets the default remove icon when `removeIcon` is omitted.
-     * `input` uses `Remove` (×); `select` uses `Minus` (−).
+     * Minimum number of rows the group must keep. Remove buttons are hidden
+     * while the row count is at or below this value.
+     *
+     * - `1` (default) — the last remaining row cannot be removed.
+     * - `0` — every row can be removed, so the list may become empty. Use this
+     *   when having no items is a valid state.
      */
-    contentType?: ItemerGroupContentType;
+    minRows?: number;
     /**
-     * Icon component for row remove buttons — any export from `@xsolla/xui-icons-base`
-     * (e.g. `Remove`, `Minus`). Overrides the `contentType` default.
+     * Maximum number of rows the group accepts. Once the row count reaches this
+     * value the whole action row below the list — the built-in add button *and*
+     * any `actions`, such as an "Upload file" button — is hidden, so no further
+     * item can be added.
+     *
+     * Omit for an unbounded list (the default).
+     */
+    maxRows?: number;
+    /**
+     * Which built-in icon the row remove buttons use. Independent of the kind of
+     * control rendered in the rows.
+     */
+    removeButtonIcon?: ItemerGroupRemoveButtonIcon;
+    /**
+     * Escape hatch for an arbitrary icon component from `@xsolla/xui-icons-base`.
+     * Overrides `removeButtonIcon`.
      */
     removeIcon?: ItemerGroupRemoveIcon;
+    /**
+     * Width of each control column, applied to both the label row and every
+     * `ItemerGroupRow`. Omit for equal-width columns.
+     *
+     * Columns beyond the end of the array fall back to an equal share.
+     */
+    columnWidths?: ItemerGroupColumnWidth[];
     onAdd?: () => void;
     addButtonLabel?: string;
     showAddButton?: boolean;
+    /**
+     * Extra action buttons rendered in the row below the list, after the
+     * built-in add button — for example an "Upload file" `Button` that opens a
+     * file picker. The row is rendered when either the add button or `actions`
+     * is present, so `showAddButton={false}` + `actions` gives an upload-only
+     * variant.
+     *
+     * Hidden together with the add button once `maxRows` is reached.
+     */
+    actions?: ReactNode;
+    className?: string;
+    testID?: string;
+}
+interface ItemerGroupFileCellProps extends ThemeOverrideProps {
+    /** File name (or any primary text). Truncated with an ellipsis. */
+    name: string;
+    /** Secondary text shown on the right, typically the file size (`"1.5MB"`). */
+    meta?: string;
+    /**
+     * Highlights the cell as invalid without rendering a message. Use it when
+     * the validation text lives elsewhere on the page.
+     */
+    error?: boolean;
+    /**
+     * Validation message rendered below the cell — for example when an uploaded
+     * file is too large. Implies `error`, so it does not have to be set as well.
+     */
+    errorMessage?: string;
+    className?: string;
+    testID?: string;
+}
+interface ItemerGroupPreviewProps extends ThemeOverrideProps {
+    /**
+     * Image URL. When omitted the preview renders a neutral placeholder with a
+     * file icon.
+     */
+    src?: string;
+    alt?: string;
+    /**
+     * Renders a spinner in place of the image or the file-icon placeholder while
+     * the thumbnail is being resolved — for example while fetching the preview
+     * of a link the user has just pasted. Takes precedence over `src`.
+     */
+    loading?: boolean;
+    /** Accessible label announced while `loading` is set. */
+    loadingLabel?: string;
     className?: string;
     testID?: string;
 }
 interface ItemerGroupRowProps {
+    /**
+     * Row content. Any control is allowed — `Input` and `Select` are the common
+     * cases, but a date picker or anything else works too. Each direct child
+     * becomes one column, sized by the parent's `columnWidths`.
+     */
     children: ReactNode;
+    /**
+     * Removes this row. The button is hidden automatically while this is the
+     * last remaining row of the group.
+     */
     onRemove?: () => void;
-    onAdd?: () => void;
     className?: string;
 }
 
@@ -37,11 +138,46 @@ declare const ItemerGroup: React__default.FC<ItemerGroupProps>;
 
 declare const ItemerGroupRow: React__default.FC<ItemerGroupRowProps>;
 
+/**
+ * Read-only row content for an uploaded file — the file name on the left and
+ * an optional meta text (typically the size) on the right, styled like a
+ * `size="sm"` input so it lines up with other controls in the group.
+ *
+ * The cell is non-interactive by design: the user cannot edit the file name
+ * despite the input-like chrome. Pass `errorMessage` to surface file-level
+ * validation (e.g. "file is too large") below the cell, matching how `Input`
+ * renders its own errors.
+ *
+ * Pair it with `ItemerGroupPreview` for a thumbnail column and with the group's
+ * `actions` slot for an "Upload file" button.
+ */
+declare const ItemerGroupFileCell: React__default.FC<ItemerGroupFileCellProps>;
+
+/**
+ * Fixed-size 77×40 thumbnail for a file row. Renders, in order of precedence:
+ * a spinner while `loading`, the image when `src` is set, and a neutral
+ * placeholder with a file icon otherwise.
+ *
+ * Because the size is fixed, give its column `"auto"` in the parent group's
+ * `columnWidths` (e.g. `columnWidths={["auto", 1]}`) so it does not stretch.
+ */
+declare const ItemerGroupPreview: React__default.FC<ItemerGroupPreviewProps>;
+
 interface ItemerGroupContextValue {
     draggable: boolean;
+    /**
+     * Number of rows in the group. `0` means the row is rendered outside an
+     * `ItemerGroup`, so the row count is unknown.
+     */
     rowCount: number;
+    /**
+     * Minimum number of rows the group keeps. Remove buttons are hidden while
+     * `rowCount <= minRows`.
+     */
+    minRows: number;
     removeIcon: ItemerGroupRemoveIcon;
+    columnWidths?: ItemerGroupColumnWidth[];
 }
 declare const ItemerGroupContext: React.Context<ItemerGroupContextValue>;
 
-export { ItemerGroup, type ItemerGroupContentType, ItemerGroupContext, type ItemerGroupProps, type ItemerGroupRemoveIcon, ItemerGroupRow, type ItemerGroupRowProps };
+export { ItemerGroup, type ItemerGroupColumnWidth, ItemerGroupContext, ItemerGroupFileCell, type ItemerGroupFileCellProps, ItemerGroupPreview, type ItemerGroupPreviewProps, type ItemerGroupProps, type ItemerGroupRemoveButtonIcon, type ItemerGroupRemoveIcon, ItemerGroupRow, type ItemerGroupRowProps };