@kanso-labs/react-native-kanso-ui 0.0.0-stage → 0.1.1

package/dist/components/number-field/index.d.ts

@@ -0,0 +1,151 @@
+import { ValidationResult } from "../../form/index.js";
+import { FieldVariant } from "../../field/index.js";
+import { StyleProp, TextInput, TextInputProps, View, ViewStyle } from "react-native";
+import { Ref } from "react";
+//#region src/components/number-field/index.d.ts
+type NumberFieldProps = Omit<TextInputProps, 'accessibilityHint' | 'accessibilityLabel' | 'aria-disabled' | 'aria-label' | 'autoComplete' | 'autoCorrect' | 'children' | 'cursorColor' | 'defaultValue' | 'editable' | 'inputMode' | 'keyboardType' | 'maxLength' | 'multiline' | 'numberOfLines' | 'onChange' | 'onChangeText' | 'placeholder' | 'placeholderTextColor' | 'readOnly' | 'selectionColor' | 'spellCheck' | 'style' | 'underlineColorAndroid' | 'value'> & {
+  /**
+   * The name of the stepper that lowers the value, for a screen reader. Left
+   * out, it is the English "Decrease" followed by the field's own label.
+   */
+  readonly decrementLabel?: string;
+  /** The value the field opens with, when it keeps its own. */
+  readonly defaultValue?: number;
+  /**
+   * A hint shown under the field. Replaced by `error` when there is one, so
+   * the two never stack.
+   */
+  readonly description?: string;
+  /**
+   * The problem with the current value, in words. Its presence is what puts
+   * the field in its error state: the message, the error colours, and the
+   * invalid state a screen reader reads all follow from it. The line under
+   * the field arrives with the message, so the field grows when this does,
+   * unless it is inside a `Form`, which keeps the line drawn. It wins over
+   * what `validate` and the form say, and holds a `native` form back.
+   */
+  readonly error?: string;
+  /**
+   * Whether the label sits in the empty box and floats to the top once the
+   * field is focused or holds a value, as the text fields page draws it.
+   * `false` keeps it small at the top in every state.
+   * @default true
+   */
+  readonly floatingLabel?: boolean;
+  /**
+   * How the value is written and read: a currency, a percentage, a unit, a
+   * number of fraction digits. It also decides what can be typed.
+   */
+  readonly formatOptions?: Intl.NumberFormatOptions;
+  /**
+   * The name of the stepper that raises the value, for a screen reader. Left
+   * out, it is the English "Increase" followed by the field's own label.
+   */
+  readonly incrementLabel?: string;
+  /**
+   * A ref to the field's own `TextInput`, which is what a call site moves
+   * focus to, after a server's error, say. `ref` is the field as a whole.
+   */
+  readonly inputRef?: Ref<TextInput>;
+  /**
+   * Draws the field disabled: it takes no focus, no input and no steps.
+   * @default false
+   */
+  readonly isDisabled?: boolean;
+  /**
+   * Shows the value and takes focus, but takes no input and no steps.
+   * @default false
+   */
+  readonly isReadOnly?: boolean;
+  /**
+   * Marks the label with an asterisk, as the text fields page marks a field
+   * that must be filled.
+   * @default false
+   */
+  readonly isRequired?: boolean;
+  /**
+   * What the field is for, and the name a screen reader reads for it.
+   * Required, since a field with no label is a box nobody can name.
+   */
+  readonly label: string;
+  /**
+   * The BCP 47 locale the value is written and read in. Defaults to the
+   * device's.
+   */
+  readonly locale?: string;
+  /** The highest value the field takes. A committed value is clamped to it. */
+  readonly maxValue?: number;
+  /** The lowest value the field takes. A committed value is clamped to it. */
+  readonly minValue?: number;
+  /**
+   * The name the value is submitted under by the `Form` around the field,
+   * and the key its `validationErrors` reach the field by. The form submits
+   * the number written out, such as `1234.5`, and `''` for an empty field.
+   */
+  readonly name?: string;
+  /**
+   * Renders the value in the mono face with tabular figures, for amounts and
+   * other numbers meant to be compared down a column. On by default, since a
+   * number field holds nothing else.
+   * @default true
+   */
+  readonly numeric?: boolean;
+  /**
+   * Called with the committed value, once it is read from what was typed or
+   * stepped to. `NaN` is an empty field.
+   */
+  readonly onChange?: (value: number) => void;
+  readonly ref?: Ref<View>;
+  /**
+   * The amount the steppers move the value by, and the multiple of it, from
+   * `minValue`, that a committed value snaps to.
+   */
+  readonly step?: number;
+  /**
+   * How the two steppers sit at the end of the box: stacked, the plus over
+   * the minus, flush with the box's edge, or side by side as extra-small
+   * icon buttons.
+   * @default 'vertical'
+   */
+  readonly steppers?: 'horizontal' | 'vertical';
+  /** Positions and sizes the field as a whole. */
+  readonly style?: StyleProp<ViewStyle>;
+  /**
+   * Checks the value, `NaN` for an empty field, and returns its problem in
+   * words, or several, where there is one, and `true`, `null` or `undefined`
+   * where there is none. Under the default `aria` validation the error shows
+   * as the value changes; inside a `native` form it shows once a submission
+   * is tried, or once the field loses focus after an edit, and holds the form
+   * back.
+   */
+  readonly validate?: (value: number) => ValidationResult;
+  /** The value, when the call site keeps it. `NaN` is an empty field. */
+  readonly value?: number;
+  /**
+   * The filled box, or the outlined one: no fill, an outline that thickens
+   * and takes the primary role while focused, and the label cutting it once
+   * it floats, the text fields page's two fields.
+   * @default 'filled'
+   */
+  readonly variant?: FieldVariant;
+};
+/**
+ * A labelled number input with steppers, the text fields page's filled or
+ * outlined field. Pass `value` with `onChange` to control it, or
+ * `defaultValue` to let it keep its own; `onChange` is handed the committed
+ * number, `NaN` for an empty field. `minValue`, `maxValue` and `step` shape
+ * it, and `formatOptions` says how it reads, in `locale`: a currency, a
+ * percentage, a unit.
+ *
+ * React Native's own `TextInput` props, the return key among them, reach the
+ * control; `style` and `ref` are the field as a whole, and `inputRef` the
+ * control.
+ *
+ * ```tsx
+ * <NumberField defaultValue={1234.5} label="Label" />
+ * ```
+ */
+declare function NumberField({ decrementLabel, defaultValue, description, error, floatingLabel, formatOptions, incrementLabel, inputRef, isDisabled, isReadOnly, isRequired, label, locale, maxValue, minValue, name, numeric, onBlur, onChange, onFocus, onSubmitEditing, ref, returnKeyType, step, steppers, style, validate, value, variant, ...props }: NumberFieldProps): import("react").JSX.Element;
+//#endregion
+export { NumberField, type NumberFieldProps };
+//# sourceMappingURL=index.d.ts.map