@redis-ui/components 43.0.2 → 43.2.1

package/skills/redis-ui-components/references/NumericInput.md

@@ -0,0 +1,322 @@
+# NumericInput
+
+A numeric input with status indicators, constraint validation, reset/loading add-ons, and a low-level compose API for custom read-only rendering.
+
+## Import
+```tsx
+import { NumericInput } from '@redislabsdev/redis-ui-components';
+```
+
+## Props
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| id | `string` | `auto-generated` | Shared id used by `FormField` and read-only rendering. Custom ids should start with a letter. |
+| variant | `'outline' \| 'underline'` | `'outline'` | Visual variant of the input shell. |
+| error | `ReactElement \| string` | - | Error content. Enables error status and tooltip content. |
+| valid | `boolean` | `false` | Enables success status. |
+| readOnly | `boolean` | `false` | Switches the input to read-only rendering. |
+| value | `number \| null` | - | Controlled numeric value. |
+| defaultValue | `number \| null` | - | Initial value for uncontrolled usage. |
+| onChange | `(newValue: number \| null) => void` | - | Called when the parsed numeric value changes. |
+| min | `number` | - | Minimum numeric constraint. |
+| max | `number` | - | Maximum numeric constraint. |
+| step | `number` | `1` | Step size used for Up/Down actions. |
+| required | `boolean` | `false` | Requires a non-empty value when auto-validating. |
+| maxDecimals | `number` | - | Maximum fractional digits used by the validator. |
+| autoValidate | `boolean` | `false` | Snaps typed values to constraints automatically. |
+| validate | `(params: { value: number \| null; min: number; max: number; required: boolean; maxDecimals: number; }) => number \| null` | built-in validator | Custom constraint validation callback. |
+| calcStepActionValue | `(params: { value: number \| null; action: 'increment' \| 'decrement'; step: number; }) => number \| null` | built-in step calculator | Custom step calculation callback. |
+| autoSize | `boolean` | `false` | Makes the input width follow its content. |
+| loading | `boolean` | `false` | Shows the loading indicator. |
+| allowReset | `boolean` | `false` | Shows the reset button when a value is present. |
+| native input props | `Omit<InputHTMLAttributes<HTMLInputElement>, 'children' \| 'defaultValue' \| 'value' \| 'onChange' \| 'min' \| 'max' \| 'type' \| 'step' \| 'required'>` | - | All remaining native `<input>` attributes, such as `placeholder`, `disabled`, `name`, `className`, `style`, `autoComplete`, and ARIA props. |
+
+The component also fixes the underlying input to `type="text"` and forwards the remaining native input attributes to the input tag.
+
+## Sub-components
+
+- `NumericInput.Compose` - Low-level compose wrapper for the input shell, value provider, and custom read-only rendering.
+- `NumericInput.Tag` - The actual input element. Supports `autoSize` and the remaining native input props.
+- `NumericInput.StatusIndicator` - Renders the success or error indicator for the current field status.
+- `NumericInput.LoadingIndicator` - Renders the loading indicator when `loading` is `true`.
+- `NumericInput.ResetButton` - Renders the reset action when `allowReset` is enabled and the field has a value.
+- `NumericInput.ReadonlyValue` - Default read-only renderer used by `NumericInput.Compose`.
+
+## Examples
+
+### Playground
+```tsx
+import { NumericInput } from '@redislabsdev/redis-ui-components';
+
+<NumericInput placeholder="NumericInput" id="custom-id" disabled={false} />;
+```
+
+### Status
+> Adding `valid` enables success status.
+>
+> Adding text to `error` enables error status. Hover the error indicator to see the tooltip.
+>
+> Error status overrides valid status.
+```tsx
+import { NumericInput } from '@redislabsdev/redis-ui-components';
+
+<>
+  Valid status
+  <NumericInput placeholder="Numeric Input" valid />
+  Error status
+  <NumericInput placeholder="Numeric Input" error="Error message" />
+</>
+```
+
+### Loading
+> Adding `loading` enables the loading indicator.
+>
+> It can be combined with other indicators and states.
+```tsx
+import { NumericInput } from '@redislabsdev/redis-ui-components';
+
+<>
+  Loading indicator
+  <NumericInput placeholder="Numeric Input" loading />
+  With other elements
+  <NumericInput placeholder="Numeric Input" defaultValue={123.1} valid allowReset loading />
+</>
+```
+
+### ResetButton
+> NumericInput allows users to clear the value. Set `allowReset` to show the reset button.
+```tsx
+import { NumericInput } from '@redislabsdev/redis-ui-components';
+
+<NumericInput placeholder="Numeric Input" defaultValue={123.1} allowReset />;
+```
+
+### DisabledAndReadonly
+> Adding `disabled` or `readOnly` switches the component to disabled or read-only states.
+>
+> In read-only mode only the value is visible. Other indicators are ignored.
+>
+> `readOnly` overrides `disabled`.
+```tsx
+import { NumericInput } from '@redislabsdev/redis-ui-components';
+
+<>
+  Disabled
+  <NumericInput disabled />
+  Disabled with value
+  <NumericInput disabled defaultValue={123.1} />
+  Disabled with indicators
+  <NumericInput disabled defaultValue={123.1} error="Error message" allowReset />
+  Read only
+  <NumericInput value={123.1} readOnly />
+</>
+```
+
+### WithLabel
+> NumericInput does not render its own label or other external decoration elements.
+>
+> Use `FormField` as a wrapper for that purpose. If a custom id is provided, `FormField` uses it; otherwise the label is connected to the generated id.
+>
+> Custom ids must start with a letter to work correctly.
+>
+> `FormField` also inherits the field status and other states.
+```tsx
+import { FormField, NumericInput } from '@redislabsdev/redis-ui-components';
+
+<>
+  <FormField label="FormField Label with custom id">
+    <NumericInput placeholder="Numeric Input" id="custom-id" />
+  </FormField>
+  <FormField
+    label="FormField Label with auto-generated id"
+    additionalText="FormField additional text"
+  >
+    <NumericInput placeholder="Numeric Input" />
+  </FormField>
+  <FormField
+    label="FormField Label with read-only mode"
+    additionalText="FormField additional text"
+  >
+    <NumericInput value={123.1} readOnly />
+  </FormField>
+</>
+```
+
+### Variants
+```tsx
+import { FormField, NumericInput } from '@redislabsdev/redis-ui-components';
+
+<>
+  <FormField label="Outline (default)" additionalText="outline">
+    <NumericInput placeholder="Numeric Input" />
+  </FormField>
+  <FormField label="Underline" additionalText="underline">
+    <NumericInput placeholder="Numeric Input" variant="underline" />
+  </FormField>
+</>
+```
+
+### AutoSize
+> Regular text inputs ignore `width: auto`.
+>
+> Add `autoSize` to let NumericInput grow to its content.
+```tsx
+import { NumericInput } from '@redislabsdev/redis-ui-components';
+
+<>
+  Type text in the input boxes to see how it auto-sizes
+  <NumericInput autoSize placeholder="placeholder" />
+  NumericInput without placeholder:
+  <NumericInput autoSize defaultValue={123.1} />
+</>
+```
+
+### Validations
+> NumericInput supports the `min`, `max`, `step`, `required`, and `maxDecimals` constraints.
+>
+> Constraints are applied while typing and on blur when `autoValidate` is enabled, and always on step actions.
+>
+> `validate` can override the default constraint validator.
+>
+> `calcStepActionValue` can override the step calculation logic.
+```tsx
+import { useState } from 'react';
+import { FormField, NumericInput, Switch } from '@redislabsdev/redis-ui-components';
+
+function Render() {
+  const [props, setProps] = useState<{
+    min?: number;
+    max?: number;
+    step?: number;
+    required: boolean;
+  }>({ min: -99, max: 99, step: 10, required: false });
+  const [val1, setVal1] = useState<number | null>(null);
+  const [val2, setVal2] = useState<number | null>(null);
+  const [val3, setVal3] = useState<number | null>(null);
+  const [val4, setVal4] = useState<number | null>(null);
+
+  return (
+    <>
+      <strong>
+        Edit constraints, type a number, press Up/Down for step actions, and blur the input to see
+        how each constraint behaves.
+      </strong>
+      <div>
+        <strong>Constraints</strong>
+        <div>
+          <FormField label="min">
+            <NumericInput
+              value={props.min}
+              onChange={(min) => setProps((state) => ({ ...state, min: min ?? undefined }))}
+            />
+          </FormField>
+          <FormField label="max">
+            <NumericInput
+              value={props.max}
+              onChange={(max) => setProps((state) => ({ ...state, max: max ?? undefined }))}
+            />
+          </FormField>
+          <FormField label="step">
+            <NumericInput
+              value={props.step}
+              autoValidate
+              onChange={(step) => setProps((state) => ({ ...state, step: step ?? undefined }))}
+            />
+          </FormField>
+          <FormField label="required">
+            <Switch
+              checked={props.required}
+              onCheckedChange={() => setProps((state) => ({ ...state, required: !state.required }))}
+            />
+          </FormField>
+        </div>
+      </div>
+      <FormField
+        label={`Regular (value: ${val1})`}
+        additionalText="errors should be detected in custom way (step always validates min-max constraints)"
+        required={props.required}
+      >
+        <NumericInput {...props} value={val1} onChange={setVal1} />
+      </FormField>
+      <FormField
+        label={`Auto Validated (value: ${val2})`}
+        additionalText="constraints are validating inside and outside we have valid value"
+        required={props.required}
+      >
+        <NumericInput {...props} value={val2} onChange={setVal2} autoValidate />
+      </FormField>
+      <FormField
+        label={`Custom Step Calculation (value: ${val3})`}
+        additionalText="step value is calculated as a simple addition of the step size to the current value"
+        required={props.required}
+      >
+        <NumericInput
+          {...props}
+          value={val3}
+          onChange={setVal3}
+          calcStepActionValue={(params) =>
+            (params.value ?? (params.action === 'increment' ? props.min : props.max) ?? 0) +
+            (params.action === 'increment' ? params.step : -params.step)
+          }
+        />
+      </FormField>
+      <FormField
+        label={`Custom Validation (value: ${val4})`}
+        additionalText="makes the value a multiple of the step size (no other constraints applied)"
+        required={props.required}
+      >
+        <NumericInput
+          {...props}
+          value={val4}
+          onChange={setVal4}
+          autoValidate
+          validate={(params) =>
+            params.value && Math.round(params.value / (props.step || 1)) * (props.step || 1)
+          }
+        />
+      </FormField>
+    </>
+  );
+}
+```
+
+### ComposeReadOnly
+```tsx
+import {
+  InputReadonlyRenderProps,
+  NumericInput
+} from '@redislabsdev/redis-ui-components';
+
+<NumericInput.Compose
+  readOnly
+  defaultValue={123.1}
+  readonlyRender={({ value, ...restProps }: InputReadonlyRenderProps) => (
+    <NumericInput.ReadonlyValue {...restProps} style={{ color: 'red' }}>
+      read-only:💚💛{' '}
+      <span
+        style={{
+          fontSize: '16px',
+          border: '1px dashed red',
+          color: 'blue',
+          borderRadius: 6,
+          padding: 3
+        }}
+      >
+        {value?.toUpperCase()}
+      </span>{' '}
+      💙💗
+    </NumericInput.ReadonlyValue>
+  )}
+>
+  <NumericInput.Tag />
+</NumericInput.Compose>
+```
+
+## Notes
+- `NumericInput` uses `type="text"` internally and the tag drives numeric keyboard behavior.
+- `allowReset` is off by default; the reset button only appears when the field has a value.
+- `readOnly` hides other indicators and overrides `disabled`.
+- `autoSize` is required if you want the input width to follow its content.
+- Use `FormField` when you need an external label, required marker, or inherited field status.
+- `NumericInput.Compose` is the entry point for custom read-only rendering and lower-level composition.
+- The built-in validator snaps values to the configured constraints when `autoValidate` is enabled.

package/skills/redis-ui-components/references/Overflow.md

@@ -0,0 +1,127 @@
+# Overflow
+
+Horizontal auto-collapsing item list that hides overflowing children and can render an extra summary item for hidden content.
+
+## Import
+
+```tsx
+import { Overflow } from '@redislabsdev/redis-ui-components';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `React.ReactNode` | required | Items to measure and collapse when they do not fit in the container |
+| renderExtra | `(visibleCount: number) => React.ReactNode` | - | Renders the extra item that summarizes hidden content |
+| estimatedItemsPerRow | `number` | `5` | Initial estimate used to calculate how many items to render before measurement completes |
+| maxRows | `number` | `1` | Maximum number of rows to display before collapsing items |
+| minItems | `number` | `0` | Minimum number of items to keep visible |
+| expectedGap | `number` | - | Expected gap between items when the component cannot infer it from styles |
+| style | `React.CSSProperties` | - | Inline styles applied to the overflow container |
+| className | `string` | - | Class name applied to the overflow container |
+
+## Examples
+
+### Playground
+
+```tsx
+import { Overflow } from '@redislabsdev/redis-ui-components';
+
+const items = Array.from({ length: 10 }, (_, index) => `Item ${index + 1}`);
+
+<Overflow
+  renderExtra={(visibleCount) => <span>+{items.length - visibleCount}</span>}
+  style={{ gap: 10 }}
+>
+  {items.map((item) => (
+    <span key={item} style={{ overflow: 'hidden' }}>
+      {item}
+    </span>
+  ))}
+</Overflow>
+```
+
+### ExactItemCount
+
+> Setting `maxRows` to 0 shows `minItems` count.
+
+```tsx
+import { Overflow } from '@redislabsdev/redis-ui-components';
+
+const items = Array.from({ length: 20 }, (_, index) => `Item ${index + 1}`);
+
+<Overflow
+  renderExtra={(visibleCount) => <span>+{items.length - visibleCount}</span>}
+  style={{ gap: 10 }}
+  maxRows={0}
+  minItems={3}
+>
+  {items.map((item) => (
+    <span key={item} style={{ overflow: 'hidden' }}>
+      {item}
+    </span>
+  ))}
+</Overflow>
+```
+
+### SingleRow
+
+> Setting `maxRows` to 1 (default) enforces `Overflow` to be single line.
+
+```tsx
+import { Overflow } from '@redislabsdev/redis-ui-components';
+
+const items = Array.from({ length: 20 }, (_, index) => `Item ${index + 1}`);
+
+<Overflow renderExtra={(visibleCount) => <span>+{items.length - visibleCount}</span>} style={{ gap: 10 }}>
+  {items.map((item) => (
+    <span key={item} style={{ overflow: 'hidden' }}>
+      {item}
+    </span>
+  ))}
+</Overflow>
+```
+
+### WithoutExtra
+
+> If `renderExtra` prop is not defined, then extra item is not rendered and ignored in calculations.
+
+```tsx
+import { Overflow } from '@redislabsdev/redis-ui-components';
+
+const items = Array.from({ length: 20 }, (_, index) => `Item ${index + 1}`);
+
+<Overflow style={{ gap: 10 }}>
+  {items.map((item) => (
+    <span key={item} style={{ overflow: 'hidden' }}>
+      {item}
+    </span>
+  ))}
+</Overflow>
+```
+
+### MultiRow
+
+> Setting `maxRows` to number larger than 1 allows `Overflow` to show items in multiple line up to the number.
+
+```tsx
+import { Overflow } from '@redislabsdev/redis-ui-components';
+
+const items = Array.from({ length: 100 }, (_, index) => `Item ${index + 1}`);
+
+<Overflow renderExtra={(visibleCount) => <span>+{items.length - visibleCount}</span>} style={{ gap: 10 }} maxRows={3}>
+  {items.map((item) => (
+    <span key={item} style={{ overflow: 'hidden' }}>
+      {item}
+    </span>
+  ))}
+</Overflow>
+```
+
+## Notes
+
+- `Overflow` measures its children and hides those that do not fit in the available width.
+- `renderExtra` is optional; when omitted, no extra summary item is rendered.
+- `maxRows` controls whether the component behaves as a single-row or multi-row overflow list.
+- Children must be React elements with unique keys.

package/skills/redis-ui-components/references/Pagination.md

@@ -0,0 +1,151 @@
+# Pagination
+
+Compound pagination primitives for rendering page navigation, page selection, page-size selection, and derived status labels. The repo exercises this API through the table pagination docs; there is no standalone `Pagination` story folder.
+
+## Import
+
+```tsx
+import { Pagination } from '@redislabsdev/redis-ui-components';
+```
+
+## Props
+
+### `Pagination.Compose`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `React.ReactNode` | - | Pagination content rendered inside the context provider |
+| pageIndex | `number` | clamped to `0..pageCount - 1` | Current page index |
+| pageSize | `number` | minimum `1` | Current page size |
+| pageCount | `number` | minimum `0` | Total number of pages |
+| totalItemCount | `number` | - | Total item count for derived labels |
+| visibleItemCount | `number` | - | Visible item count for derived labels |
+| getCanGoNextPage | `() => boolean` | `() => pageIndex < pageCount - 1` | Overrides whether the next-page action is enabled |
+| getCanGoPrevPage | `() => boolean` | `() => pageIndex > 0` | Overrides whether the previous-page action is enabled |
+| getCanSelectPage | `() => boolean` | `() => pageCount > 1` | Overrides whether page selection is enabled |
+| getCanSelectPageSize | `() => boolean` | `() => !!(totalItemCount !== 0 && onPageSizeChange)` | Overrides whether page-size selection is enabled |
+| onPageSizeChange | `(count: number) => void` | - | Called when page size changes |
+| onPageChange | `(page: number) => void` | required | Called when page changes |
+| onNextPage | `() => void` | `() => onPageChange(pageIndex + 1)` | Overrides the next-page action |
+| onFirstPage | `() => void` | `() => onPageChange(0)` | Overrides the first-page action |
+| onPrevPage | `() => void` | `() => onPageChange(pageIndex - 1)` | Overrides the previous-page action |
+| onLastPage | `() => void` | `() => onPageChange(pageCount - 1)` | Overrides the last-page action |
+
+### `Pagination.InfoLabel`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| renderer | `(params: PaginationState) => ReactNode` | required | Renders derived pagination text from the current pagination state |
+| other `Typography.Body` props | `ChildFree<ComponentProps<typeof Typography.Body>>` | - | Passed through to the underlying `Typography.Body` |
+
+### `Pagination.NavigationButton`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| navType | `'prev' \| 'next' \| 'first' \| 'last'` | required | Chooses which navigation action and icon to render |
+| other `IconButton` props | `Partial<IconButtonProps>` | - | Passed through to the underlying `IconButton` |
+
+### `Pagination.PageSelect`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| other `Select` props | `Omit<SelectProps, 'value' \| 'onChange' \| 'disabled' \| 'options'>` | - | Passed through to the underlying `Select` |
+
+### `Pagination.PageSelect.Label`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| other `Typography.Body` props | `ComponentProps<typeof Typography.Body>` | - | Passed through to the label typography |
+
+### `Pagination.PageSizeSelect`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| pageSizes | `number[]` | `[10, 25, 50, 100]` | Page sizes shown in the selector |
+| other `Select` props | `Omit<SelectProps, 'value' \| 'onChange' \| 'disabled' \| 'options'>` | - | Passed through to the underlying `Select` |
+
+### `Pagination.PageSizeSelect.Label`
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| other `Typography.Body` props | `ComponentProps<typeof Typography.Body>` | - | Passed through to the label typography |
+
+## Sub-components
+
+- `Pagination.Compose` - Provides `PaginationContext` and default navigation/validation handlers.
+- `Pagination.Bar` - Layout container for the pagination row.
+- `Pagination.Group` - Flex wrapper for grouping pagination controls.
+- `Pagination.Split` - Spacer primitive that pushes adjacent groups apart.
+- `Pagination.InfoLabel` - Renders derived pagination state text.
+- `Pagination.NavigationButton` - Renders first, previous, next, and last navigation buttons.
+- `Pagination.PageSelect` - Select control for choosing a page.
+- `Pagination.PageSelect.Label` - Label paired with the page selector id.
+- `Pagination.PageSizeSelect` - Select control for choosing the page size.
+- `Pagination.PageSizeSelect.Label` - Label paired with the page-size selector id.
+
+## Examples
+
+### Table Composition
+
+> There is no standalone `Pagination` story folder. The only story-backed usage lives in the table pagination docs, where `Table` layers additional grouping wrappers around these pagination primitives.
+> The `PageSizeGroup`, `PageNavGroup`, and `PageSelectGroup` wrappers in that example belong to the table docs, not the standalone `Pagination` export.
+
+```tsx
+import { Table } from '@redislabsdev/redis-ui-table';
+import { PaginationInfoLabelProps } from '@redislabsdev/redis-ui-components';
+import { columns, tableData } from './TableStory.data';
+
+const renderRowCount: PaginationInfoLabelProps['renderer'] = ({ visibleItemCount, totalItemCount }) =>
+  `Showing ${visibleItemCount} out of ${totalItemCount} rows`;
+
+const renderPageCount: PaginationInfoLabelProps['renderer'] = ({ pageIndex, pageCount }) =>
+  `${pageIndex + 1} of ${pageCount}`;
+
+const renderTotalPageCount: PaginationInfoLabelProps['renderer'] = ({ pageCount }) => `of ${pageCount}`;
+
+<Table.Compose
+  data={tableData}
+  columns={columns}
+  pluginsData={[Table.usePaginationPlugin({ paginationEnabled: true })]}
+>
+  <Table.Pagination.Compose>
+    <Table.Pagination.Bar>
+      <Table.Pagination.InfoLabel renderer={renderRowCount} ellipsis tooltipOnEllipsis />
+      <Table.Pagination.Split />
+      <Table.Pagination.PageSizeGroup>
+        <Table.Pagination.PageSizeSelect.Label>
+          Items per page:
+        </Table.Pagination.PageSizeSelect.Label>
+        <Table.Pagination.PageSizeSelect />
+      </Table.Pagination.PageSizeGroup>
+      <Table.Pagination.PageNavGroup>
+        <div>
+          <Table.Pagination.NavigationButton navType="first" />
+          <Table.Pagination.NavigationButton navType="prev" />
+        </div>
+        <Table.Pagination.InfoLabel ellipsis tooltipOnEllipsis renderer={renderPageCount} />
+        <div>
+          <Table.Pagination.NavigationButton navType="next" />
+          <Table.Pagination.NavigationButton navType="last" />
+        </div>
+      </Table.Pagination.PageNavGroup>
+      <Table.Pagination.PageSelectGroup>
+        <Table.Pagination.PageSelect.Label>Page</Table.Pagination.PageSelect.Label>
+        <Table.Pagination.PageSelect />
+        <Table.Pagination.InfoLabel
+          ellipsis
+          tooltipOnEllipsis
+          renderer={renderTotalPageCount}
+        />
+      </Table.Pagination.PageSelectGroup>
+    </Table.Pagination.Bar>
+  </Table.Pagination.Compose>
+</Table.Compose>
+```
+
+## Notes
+
+- Pagination is handled internally when the pagination prop is not provided.
+- Pagination state can be controlled externally using the pagination prop.
+- For manual pagination, `manualPagination` must be `true` and `totalRowCount` must be provided.
+- Pagination can be used in empty tables.