@redis-ui/components 43.0.2 → 43.2.1

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

@@ -0,0 +1,555 @@
+# QuantityCounter
+
+A quantity input with status indicators, validation controls, read-only rendering, and compound composition building blocks.
+
+## Import
+
+```tsx
+import { QuantityCounter } from '@redislabsdev/redis-ui-components';
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| id | `string` | - | Shared id for the composed input field |
+| variant | `'outline' \| 'underline'` | `'outline'` | Visual variant for the composed input |
+| error | `ReactElement \| string` | - | Error content; also drives error status |
+| valid | `boolean` | `false` | Enables success status |
+| readOnly | `boolean` | `false` | Switches the field into read-only mode |
+| value | `number \| null` | - | Controlled numeric value |
+| defaultValue | `number \| null` | - | Uncontrolled initial numeric value |
+| onChange | `(newValue: number \| null) => void` | - | Called whenever the parsed numeric value changes |
+| min | `number` | - | Minimum allowed value |
+| max | `number` | - | Maximum allowed value |
+| step | `number` | `1` | Step size used by arrow keys and step buttons |
+| required | `boolean` | `false` | Requires a non-empty value when validation is enabled |
+| maxDecimals | `number` | - | Limits fractional precision when auto-validation is enabled |
+| autoValidate | `boolean` | `false` | Snaps typed values to constraints automatically |
+| validate | `Validate` | - | Custom validation / snapping function |
+| calcStepActionValue | `CalcStepActionValue` | - | Custom step value calculator for increment/decrement actions |
+| valueLabel | `string` | - | Suffix label used next to the numeric value and in read-only mode |
+| incrementButtonProps | `Omit<QuantityCounterStepButtonProps, 'action'>` | - | Overrides for the increment button |
+| decrementButtonProps | `Omit<QuantityCounterStepButtonProps, 'action'>` | - | Overrides for the decrement button |
+
+The component also forwards the remaining native `InputHTMLAttributes<HTMLInputElement>` props that are not omitted in `RestQuantityCounterProps`, such as `className`, `style`, `disabled`, `placeholder`, `name`, and `autoComplete`.
+
+## Sub-components
+
+- `QuantityCounter.Compose` - Base compound wrapper that wires numeric state, validation, and read-only rendering.
+- `QuantityCounter.InputGroup` - Input-and-label wrapper for the editable or read-only field.
+- `QuantityCounter.InputGroup.Compose` - Low-level flex container used to build custom input-group layouts.
+- `QuantityCounter.InputGroup.Tag` - Auto-sized input element used for the numeric field.
+- `QuantityCounter.InputGroup.ValueLabel` - Suffix label rendered after the numeric value.
+- `QuantityCounter.StepButton` - Increment or decrement action button with default plus/minus icons.
+- `QuantityCounter.ReadonlyValue` - Styled read-only value wrapper used by custom read-only renderers.
+
+### QuantityCounter.Compose Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| id | `string` | - | Shared id for the compound field |
+| variant | `'outline' \| 'underline'` | `'outline'` | Compound field variant |
+| error | `ReactElement \| string` | - | Error content propagated to the field state |
+| valid | `boolean` | `false` | Success state flag |
+| readOnly | `boolean` | `false` | Read-only mode flag |
+| value | `number \| null` | - | Controlled value |
+| defaultValue | `number \| null` | - | Uncontrolled initial value |
+| onChange | `(newValue: number \| null) => void` | - | Value change handler |
+| min | `number` | - | Minimum constraint |
+| max | `number` | - | Maximum constraint |
+| step | `number` | `1` | Step size for validation and stepping |
+| required | `boolean` | `false` | Required flag for validation |
+| maxDecimals | `number` | - | Fractional precision limit |
+| autoValidate | `boolean` | `false` | Enables automatic constraint snapping |
+| validate | `Validate` | - | Custom validation hook |
+| calcStepActionValue | `CalcStepActionValue` | - | Custom step computation hook |
+| valueLabel | `string` | - | Label suffix used in read-only rendering |
+| readonlyRender | `ReadOnlyRenderComponent` | Generated from `valueLabel` when provided | Custom read-only renderer |
+| readonlyProps | `HTMLAttributes<HTMLElement>` | - | Additional props passed to the read-only wrapper |
+| children | `ReactNode` | - | Nested compound content |
+
+The compose wrapper also accepts the remaining `ComposeElementProps` from the shared numeric compose layer, including standard container attributes such as `children`, `className`, `style`, and event handlers.
+
+### QuantityCounter.InputGroup Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| valueLabel | `string` | - | Text shown after the numeric value |
+
+The wrapper also forwards the remaining native input attributes from `RestInputTagProps` to the internal input tag, including `placeholder`, `disabled`, `autoComplete`, and event handlers.
+
+### QuantityCounter.InputGroup.Compose Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `ReactNode` | - | Nested input-group content |
+
+This component is a layout wrapper and also accepts standard container attributes from `ComposeElementProps`.
+
+### QuantityCounter.InputGroup.Tag Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| autoSize | `boolean` | `true` | Forces the input to auto-size inside the quantity counter |
+| aria-description | `string` | `Press up or down arrow keys to change the value` | Describes the keyboard step interaction |
+
+The tag also accepts native input props. The underlying input defaults to `type="text"` and `autoComplete="off"`.
+
+### QuantityCounter.InputGroup.ValueLabel Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| children | `string \| ReactElement` | - | Value label content shown next to the numeric value |
+
+If there is no value or no label content, the component renders nothing.
+
+### QuantityCounter.StepButton Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| action | `'increment' \| 'decrement'` | required | Chooses whether the button increments or decrements the value |
+| variant | `'primary' \| 'secondary'` | `'secondary'` | Button styling variant |
+| size | `'L' \| 'M' \| 'S' \| 'XS'` | `'S'` | Icon button size |
+| icon | `IconType` | `PlusIcon` or `MinusIcon` depending on `action` | Overrides the default plus/minus icon |
+| title | `string` | `Increment` or `Decrement` depending on `action` | Accessible title / tooltip text |
+| disabled | `boolean` | - | Manually disables the step button |
+| onClick | `MouseEventHandler<HTMLButtonElement>` | - | Click handler for the step button |
+| onMouseDown | `MouseEventHandler<HTMLButtonElement>` | - | Mouse-down handler for the step button |
+
+The button also accepts the remaining `ActionIconButtonProps` and native button attributes. Internally it forces `tabIndex={-1}` and hides itself from assistive tech because the input drives the interaction.
+
+### QuantityCounter.ReadonlyValue Props
+
+This is the shared read-only text wrapper used by custom read-only renderers. It behaves like the underlying `Typography.Body` wrapper and is typically paired with `ReadonlyRenderProps` inside `QuantityCounter.Compose`.
+
+## Examples
+
+### Basic Usage
+
+```tsx
+import { QuantityCounter } from '@redislabsdev/redis-ui-components';
+
+<QuantityCounter placeholder="QuantityCounter" id="custom-id" disabled={false} valueLabel="MB" />;
+```
+
+### Status
+
+> Adding `valid` prop enables valid status.
+>
+> Adding some text to the `error` prop of `QuantityCounter` enables error status. Hover the error indicator to see the tooltip.
+>
+> Error status overrides valid status.
+
+```tsx
+import { QuantityCounter } from '@redislabsdev/redis-ui-components';
+
+<>
+  Valid status
+  <QuantityCounter valueLabel="MB" placeholder="Quantity Counter" valid />
+  Error status (hover for tooltip)
+  <QuantityCounter valueLabel="MB" placeholder="Quantity Counter" error="Error message" />
+</>
+```
+
+### DisabledAndReadonly
+
+> Adding `disabled` or `readOnly` prop switches the component to disabled or read-only states accordingly.
+>
+> In read-only mode only the value is visible. Other indicators are ignored.
+>
+> Read-only overrides disabled.
+
+```tsx
+import { QuantityCounter } from '@redislabsdev/redis-ui-components';
+
+<>
+  Disabled
+  <QuantityCounter valueLabel="MB" disabled />
+  Disabled with value
+  <QuantityCounter valueLabel="MB" disabled defaultValue={123.1} />
+  Disabled with error status (hover for tooltip)
+  <QuantityCounter valueLabel="MB" disabled defaultValue={123.1} error="Error message" />
+  Read only
+  <QuantityCounter valueLabel="MB" value={123.1} readOnly />
+</>
+```
+
+### DisabledStepButtons
+
+> Step buttons can be disabled conditionally or forcibly.
+>
+> Forced disabling is not recommended, because step actions are still available, for example via keyboard.
+>
+> Conditional disabling works if range bounds are defined with `min` and `max`.
+
+```tsx
+import { QuantityCounter } from '@redislabsdev/redis-ui-components';
+
+<>
+  Forcibly disabled increment button (not recommended)
+  <QuantityCounter
+    valueLabel="MB"
+    placeholder="QuantityCounter"
+    incrementButtonProps={{ disabled: true }}
+  />
+  Forcibly disabled decrement button (not recommended)
+  <QuantityCounter
+    valueLabel="MB"
+    placeholder="QuantityCounter"
+    decrementButtonProps={{ disabled: true }}
+  />
+  Auto disabled increment button, when value reached upper range
+  <QuantityCounter valueLabel="MB" placeholder="QuantityCounter" max={10} defaultValue={10} />
+  Auto disabled decrement button, when value reached lower range
+  <QuantityCounter valueLabel="MB" placeholder="QuantityCounter" min={-10} defaultValue={-10} />
+</>
+```
+
+### WithLabel
+
+> `QuantityCounter` does not have its own label or external decoration. Use `FormField` for that.
+>
+> If a custom id is specified for the input, `FormField` inherits it; otherwise the label is auto-connected with a generated id.
+>
+> Custom ids must start with a letter to work correctly.
+>
+> `FormField` also inherits status and some states from the nested input.
+
+```tsx
+import { FormField, QuantityCounter } from '@redislabsdev/redis-ui-components';
+
+<>
+  <FormField label="FormField Label with custom id">
+    <QuantityCounter valueLabel="MB" placeholder="Quantity Counter" id="custom-id" />
+  </FormField>
+  <FormField
+    label="FormField Label with auto-generated id"
+    additionalText="FormField additional text"
+  >
+    <QuantityCounter valueLabel="MB" placeholder="Quantity Counter" />
+  </FormField>
+  <FormField
+    label="FormField Label with read-only mode"
+    additionalText="FormField additional text"
+  >
+    <QuantityCounter valueLabel="MB" value={123.1} readOnly />
+  </FormField>
+</>
+```
+
+### Variants
+
+```tsx
+import { FormField, QuantityCounter } from '@redislabsdev/redis-ui-components';
+
+<>
+  <FormField label="Outline (default)" additionalText="outline">
+    <QuantityCounter valueLabel="MB" placeholder="Quantity Counter" />
+  </FormField>
+  <FormField label="Underline" additionalText="underline">
+    <QuantityCounter valueLabel="MB" placeholder="Quantity Counter" variant="underline" />
+  </FormField>
+</>
+```
+
+### AutoSize
+
+> Unlike other text inputs, a regular input will ignore `width: auto`.
+>
+> `QuantityCounter` auto-sizes out of the box.
+
+```tsx
+import { QuantityCounter } from '@redislabsdev/redis-ui-components';
+
+<>
+  Type text in the input boxes to see how it auto-sizes
+  <QuantityCounter valueLabel="MB" placeholder="placeholder" />
+  QuantityCounter without placeholder:
+  <QuantityCounter valueLabel="MB" defaultValue={123.1} />
+</>
+```
+
+### Validations
+
+> `QuantityCounter` supports `min`, `max`, `step`, `required`, and `maxDecimals`.
+>
+> Constraints are applied when typing or blurring if `autoValidate` is enabled, and always when stepping with the keyboard or buttons.
+>
+> Validation can be overridden with `validate`.
+>
+> Step calculation can be customized with `calcStepActionValue`.
+
+```tsx
+import { useState } from 'react';
+import { FormField, QuantityCounter, Switch } from '@redislabsdev/redis-ui-components';
+import { ConstraintsGroup } from '../InputStories.style';
+
+const defValueLabel = 'MB';
+
+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 number, blur input, press Up/Down arrows or click +/- buttons to see
+        behavior of each one
+      </strong>
+      <ConstraintsGroup>
+        <strong>Constraints</strong>
+        <div>
+          <FormField label="min">
+            <QuantityCounter
+              valueLabel={defValueLabel}
+              value={props.min}
+              onChange={(min) => setProps((state) => ({ ...state, min: min ?? undefined }))}
+            />
+          </FormField>
+          <FormField label="max">
+            <QuantityCounter
+              valueLabel={defValueLabel}
+              value={props.max}
+              onChange={(max) => setProps((state) => ({ ...state, max: max ?? undefined }))}
+            />
+          </FormField>
+          <FormField label="step">
+            <QuantityCounter
+              valueLabel={defValueLabel}
+              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>
+      </ConstraintsGroup>
+      <FormField
+        label={`Regular (value: ${val1})`}
+        additionalText="errors should be detected in custom way (step always validate min-max constraints)"
+        required={props.required}
+      >
+        <QuantityCounter valueLabel={defValueLabel} {...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}
+      >
+        <QuantityCounter
+          valueLabel={defValueLabel}
+          {...props}
+          value={val2}
+          onChange={setVal2}
+          autoValidate
+        />
+      </FormField>
+      <FormField
+        label={`Custom Step Calculation (value: ${val3})`}
+        additionalText="step value is calculated as simple addition the step size to the current value"
+        required={props.required}
+      >
+        <QuantityCounter
+          valueLabel={defValueLabel}
+          {...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}
+      >
+        <QuantityCounter
+          valueLabel={defValueLabel}
+          {...props}
+          value={val4}
+          onChange={setVal4}
+          autoValidate
+          validate={(params) =>
+            params.value && Math.round(params.value / (props.step || 1)) * (props.step || 1)
+          }
+        />
+      </FormField>
+    </>
+  );
+}
+```
+
+### ComposeReadOnly
+
+```tsx
+import { QuantityCounter } from '@redislabsdev/redis-ui-components';
+
+<QuantityCounter.Compose readOnly defaultValue={123.1} valueLabel="MB">
+  <QuantityCounter.StepButton action="decrement" />
+  <QuantityCounter.InputGroup valueLabel="MB" />
+  <QuantityCounter.StepButton action="increment" />
+</QuantityCounter.Compose>;
+```
+
+> The story also supplies a custom `readonlyRender` in Storybook args to demonstrate `QuantityCounter.ReadonlyValue`.
+
+### ComposeValueLabelAsSelect
+
+> Value labels can be composed as any component instead of plain text.
+>
+> This example uses a `Select` as a dynamic value label and shows it in read-only mode too.
+>
+> The story makes the label auto-sized and wraps it with `FormField.Nested` to avoid interference with the surrounding `QuantityCounter`. It also keeps the select value in sync with `valueLabel` for the read-only view.
+
+```tsx
+import { useEffect, useState } from 'react';
+import { Button, FormField, QuantityCounter, Select } from '@redislabsdev/redis-ui-components';
+
+const defValueLabel = 'MB';
+const options = [{ value: 'MB' }, { value: 'GB' }, { value: 'TB' }];
+
+function Render({ disabled, ...args }) {
+  const [readOnly, setReadOnly] = useState(args.readOnly);
+  const [valueLabel, setValueLabel] = useState(defValueLabel);
+
+  useEffect(() => {
+    setReadOnly(args.readOnly);
+  }, [args.readOnly]);
+
+  return (
+    <>
+      <QuantityCounter.Compose {...args} readOnly={readOnly} valueLabel={valueLabel}>
+        <QuantityCounter.StepButton action="decrement" />
+        <QuantityCounter.InputGroup.Compose>
+          <QuantityCounter.InputGroup.Tag disabled={disabled} />
+          <QuantityCounter.InputGroup.ValueLabel>
+            <FormField.Nested>
+              <Select
+                options={options}
+                style={{
+                  width: 'fit-content',
+                  height: 'fit-content',
+                  border: 'none',
+                  padding: 0
+                }}
+                value={valueLabel}
+                onChange={(valueLabelSelect) => setValueLabel(valueLabelSelect)}
+              />
+            </FormField.Nested>
+          </QuantityCounter.InputGroup.ValueLabel>
+        </QuantityCounter.InputGroup.Compose>
+        <QuantityCounter.StepButton action="increment" />
+      </QuantityCounter.Compose>
+      <Button onClick={() => setReadOnly(!readOnly)} style={{ alignSelf: 'flex-start' }}>
+        Toggle Read-Only
+      </Button>
+    </>
+  );
+}
+```
+
+### ComposeValueLabelAsInput
+
+> Value labels can be composed as any component instead of plain text.
+>
+> This example uses a text `Input` as a dynamic value label.
+>
+> Make the label replacement component auto-sized and wrap it with `FormField.Nested` to avoid unnecessary interaction with the surrounding `QuantityCounter`. Keep its value controlled so the read-only mode can mirror `valueLabel`.
+
+```tsx
+import { useEffect, useState } from 'react';
+import { Button, FormField, Input, QuantityCounter } from '@redislabsdev/redis-ui-components';
+
+const defValueLabel = 'MB';
+
+function Render({ disabled, ...args }) {
+  const [readOnly, setReadOnly] = useState(args.readOnly);
+  const [valueLabel, setValueLabel] = useState(args.valueLabel);
+
+  useEffect(() => {
+    setValueLabel(args.valueLabel);
+  }, [args.valueLabel]);
+
+  useEffect(() => {
+    setReadOnly(args.readOnly);
+  }, [args.readOnly]);
+
+  return (
+    <>
+      <QuantityCounter.Compose {...args} readOnly={readOnly} valueLabel={valueLabel}>
+        <QuantityCounter.StepButton action="decrement" />
+        <QuantityCounter.InputGroup.Compose>
+          <QuantityCounter.InputGroup.Tag disabled={disabled} />
+          <QuantityCounter.InputGroup.ValueLabel>
+            <FormField.Nested>
+              <Input
+                defaultValue="TB"
+                autoSize
+                style={{
+                  width: 'fit-content',
+                  height: 'fit-content',
+                  border: 'none',
+                  padding: 0
+                }}
+                value={valueLabel}
+                onChange={(valueLabelInput) => setValueLabel(valueLabelInput)}
+              />
+            </FormField.Nested>
+          </QuantityCounter.InputGroup.ValueLabel>
+        </QuantityCounter.InputGroup.Compose>
+        <QuantityCounter.StepButton action="increment" />
+      </QuantityCounter.Compose>
+      <Button
+        onClick={() => {
+          setReadOnly(!readOnly);
+        }}
+        style={{ alignSelf: 'flex-start' }}
+      >
+        Toggle Read-Only
+      </Button>
+    </>
+  );
+}
+```
+
+### ComposeOldLook
+
+> With a few CSS changes and by reordering the compound parts you can change the view of the component.
+>
+> This example shows the old look of `QuantityCounter`.
+
+```tsx
+import { QuantityCounter } from '@redislabsdev/redis-ui-components';
+
+<QuantityCounter.Compose defaultValue={123.1} valueLabel="MB">
+  <QuantityCounter.InputGroup valueLabel="MB" style={{ justifyContent: 'flex-start' }} />
+  <QuantityCounter.StepButton action="increment" />
+  <QuantityCounter.StepButton action="decrement" />
+</QuantityCounter.Compose>
+```
+
+## Notes
+
+- `QuantityCounter` uses the shared numeric compose layer, so `readOnly` overrides `disabled`.
+- Error status overrides valid status.
+- Forced disabling of step buttons is not recommended because stepping still works from the keyboard.
+- Use `FormField` when you need labels or additional text around the counter.
+- The nested input auto-sizes by default and exposes an accessible description for the up/down key behavior.
+- `QuantityCounter.InputGroup.ValueLabel` can render either plain text or a custom element, which makes it useful for custom read-only renderers.
+- When composing a custom value label component, wrap it with `FormField.Nested` and keep it controlled so the read-only label stays in sync.