@galaxy-io/dls 1.6.0 → 2.0.0

package/dist/inputs/Input.d.ts

@@ -1,210 +1,171 @@
-import { type Ref } from "react";
 import { type Icon as PhosphorIcon } from "@phosphor-icons/react";
-import type { Theme } from "../theme/types";
-import { TextSize } from "../text/Text";
-export interface InputLabelProps {
-    label: string;
-    /** Adds an info icon beside the label with this content on hover. */
-    labelTooltip?: string | React.ReactNode;
-    /** Appends the red required asterisk. */
-    isRequired?: boolean;
-}
-/**
- * The label row every input renders above itself. Exported for building custom
- * inputs that should match — the stock inputs render it from their own props.
- */
-export declare const InputLabel: ({ label, labelTooltip, isRequired }: InputLabelProps) => import("react").JSX.Element;
-/** Field height — 24 / 28 / 32px, matching `ButtonSize` so they line up in a row. */
+import { type AriaAttributes, type CSSProperties, type InputHTMLAttributes, type ReactNode } from "react";
+import { ButtonSize } from "../buttons/Button.js";
+import { FontFamily, type Space } from "../theme/enums.js";
+/** Canonical rungs; Input supports all five. Shared by the text-like inputs that wrap Input. */
 export declare enum InputSize {
+    /** 20px tall: caption text, 12px icon. */
+    X_SMALL = "X_SMALL",
+    /** 24px tall: body_sm text, 12px icon. */
     SMALL = "SMALL",
+    /** 32px tall: body_md text, 14px icon. The default (1.x `MEDIUM` was 28px). */
     MEDIUM = "MEDIUM",
-    LARGE = "LARGE"
+    /** 36px tall: body_lg text, 14px icon. */
+    LARGE = "LARGE",
+    /** 40px tall: body_lg text, 16px icon. */
+    X_LARGE = "X_LARGE"
 }
 /**
- * Field height for an `InputSize`. The single source of truth — every input in
- * the family routes through this. Call it from inside a Linaria interpolation:
- *
- * ```
- * height: ${({ $size }) => getInputHeight($size)};
- * ```
- */
-export declare function getInputHeight(size: InputSize): string;
-/** `getInputHeight` unwrapped, for callers that need to do arithmetic on it. */
-export declare function getInputHeightValue(size: InputSize): number;
-/**
- * Horizontal inset for an `InputSize` — 6 / 8 / 12px. Returned as a number so
- * `TextAreaInput` can fold it into its computed `min-height`; most callers want
- * `getInputPadding` instead.
- */
-export declare function getInputPaddingValue(size: InputSize): number;
-/** `getInputPaddingValue` as a CSS length. */
-export declare function getInputPadding(size: InputSize): string;
-/** Type step for an `InputSize` — `body_sm` / `body_md` / `body_lg`. */
-export declare function getInputFontSize(theme: Theme, size: InputSize): string;
-/** The line height paired with `getInputFontSize`. */
-export declare function getInputLineHeight(theme: Theme, size: InputSize): string;
-/** Icon px for an `InputSize` — 12 / 14 / 16, for icons sitting inside a field. */
-export declare function getInputIconSize(size: InputSize): number;
-/**
- * `getInputFontSize` for copy that renders through `Text` rather than through a
- * raw `<input>` — the trigger labels in `SelectInput`, `DateInput`, `ColorInput`.
- */
-export declare function getInputTextSize(size: InputSize): TextSize;
-/**
- * Hit-target box for the boolean controls — 12 / 16 / 20px. Shared by the
- * `CheckboxInput` square and the `RadioInput` circle, which are sized as targets
- * rather than off the type scale, so they do not follow `getInputHeight`.
- */
-export declare function getInputControlSize(size: InputSize): string;
-/**
- * Surface color for any input. Mirrors `DropdownVariant` so a field and the
- * panel it sits in can be tuned to the same step of the neutral stack.
- *
- * Paints the *resting* surface only — state colors (checked, selected, filled)
- * are fixed tokens and are not affected by the variant.
- *
- * `TRANSPARENT` drops both the fill and the border. `CheckboxInput` and
- * `RadioInput` keep their hairline under it, or they would be invisible.
+ * Resting fill of the field (Constitution V-A surface set). 1.x `TRANSPARENT` is `isGhost` (color
+ * 2.1).
  */
 export declare enum InputVariant {
-    TRANSPARENT = "TRANSPARENT",
+    /** `background.base` fill. */
     BASE = "BASE",
+    /** `background.primary` fill. The default. */
     PRIMARY = "PRIMARY",
+    /** `background.secondary` fill. */
     SECONDARY = "SECONDARY",
+    /** `background.tertiary` fill. */
     TERTIARY = "TERTIARY"
 }
-/**
- * Surface fill for an `InputVariant`. The single source of truth — every input
- * routes through this. Call it from inside a Linaria interpolation:
- *
- * ```
- * background-color: ${({ theme, $variant }) => getInputSurfaceColor(theme, $variant)};
- * ```
- */
-export declare function getInputSurfaceColor(theme: Theme, variant?: InputVariant): string;
-/**
- * Resting border for an `InputVariant`. Callers short-circuit their own error,
- * focus and active colors before falling back to this.
- *
- * Returns `"transparent"` rather than `"none"` so the box model stays identical
- * across variants.
- */
-export declare function getInputBorderColor(theme: Theme, variant?: InputVariant): string;
-export declare const StyledInput: import("react").ComponentType<Pick<import("react").ClassAttributes<HTMLInputElement> & import("react").InputHTMLAttributes<HTMLInputElement> & {
-    $size: InputSize;
-    $variant?: InputVariant;
-    $width?: number | string;
-    $fillWidth?: boolean;
-    $isError?: boolean;
-    $hasLeadingIcon?: boolean;
-    $hasTrailingAction?: boolean;
-    $isMonospace?: boolean;
-    $isDisabled?: boolean;
-} & {
-    theme: Theme;
-} & {
-    as?: React.ElementType;
-}, "$width" | "$fillWidth" | "$size" | "$variant" | "$isMonospace" | "as" | "$isError" | "$hasLeadingIcon" | "$hasTrailingAction" | "$isDisabled" | keyof import("react").ClassAttributes<HTMLInputElement> | keyof import("react").InputHTMLAttributes<HTMLInputElement>> & {
-    theme?: import("@callstack/react-theme-provider").$DeepPartial<Theme> | undefined;
-}> & import("@callstack/react-theme-provider/typings/hoist-non-react-statics").NonReactStatics<import("react").ComponentType<import("react").ClassAttributes<HTMLInputElement> & import("react").InputHTMLAttributes<HTMLInputElement> & {
-    $size: InputSize;
-    $variant?: InputVariant;
-    $width?: number | string;
-    $fillWidth?: boolean;
-    $isError?: boolean;
-    $hasLeadingIcon?: boolean;
-    $hasTrailingAction?: boolean;
-    $isMonospace?: boolean;
-    $isDisabled?: boolean;
-} & {
-    theme: Theme;
-} & {
-    as?: React.ElementType;
-}> & {
-    __wyw_meta: unknown;
-} & import("react").FunctionComponent<import("react").ClassAttributes<HTMLInputElement> & import("react").InputHTMLAttributes<HTMLInputElement> & {
-    $size: InputSize;
-    $variant?: InputVariant;
-    $width?: number | string;
-    $fillWidth?: boolean;
-    $isError?: boolean;
-    $hasLeadingIcon?: boolean;
-    $hasTrailingAction?: boolean;
-    $isMonospace?: boolean;
-    $isDisabled?: boolean;
-} & {
-    theme: Theme;
-} & {
-    as?: React.ElementType;
-}>, {}>;
-/** What an `Input` can hold. Narrowed by each wrapper — `string`, `number`, … */
-export type InputValue = string | number | readonly string[] | undefined;
-/**
- * The shared prop surface for every text-like input. The concrete wrappers
- * (`TextInput`, `PasswordInput`, `NumberInput`, …) are `Omit`s of this, so their
- * props are documented here.
- */
-export interface InputProps<T> {
-    /** Coerces the raw string from the DOM into `T` before `onChange`. Wrappers set it. */
-    parse: (value: T) => T;
-    /** Called with the parsed value on every keystroke. */
-    onChange: (value: T) => void;
-    /** Field surface color. @default InputVariant.PRIMARY */
-    variant?: InputVariant;
-    /** @default InputSize.MEDIUM */
+/** The native types the typed wrappers use. */
+export type InputType = "text" | "password" | "search";
+/** The families a field's value may use (serif has no UI steps). */
+type InputFamily = FontFamily.SANS | FontFamily.MONO;
+/** Native `<input>` attributes Input passes through, typed as React types them (the allowlist). */
+type NativeInputAttributes = InputHTMLAttributes<HTMLInputElement>;
+/** The native passthrough allowlist, each documented. */
+interface InputNativeProps {
+    /** Form field name, passed to the `<input>`. */
+    name?: NativeInputAttributes["name"];
+    /**
+     * Browser autofill hint (`"username"`, `"email"`). Off by default so names and IDs are not autofilled.
+     * @default "off"
+     */
+    autoComplete?: NativeInputAttributes["autoComplete"];
+    /** Virtual keyboard hint (`"email"`, `"decimal"`, `"url"`). */
+    inputMode?: NativeInputAttributes["inputMode"];
+    /** Label of the virtual keyboard's Enter key (`"search"`, `"go"`, `"done"`). */
+    enterKeyHint?: NativeInputAttributes["enterKeyHint"];
+    /** Focus the input on mount. */
+    autoFocus?: NativeInputAttributes["autoFocus"];
+    /** Hard cap on the value's length. Shows no message; for a counter, use `Field`. */
+    maxLength?: NativeInputAttributes["maxLength"];
+    /** Browser spell checking. */
+    spellCheck?: NativeInputAttributes["spellCheck"];
+    /** Focus handler on the `<input>`. */
+    onFocus?: NativeInputAttributes["onFocus"];
+    /** Blur handler on the `<input>`. */
+    onBlur?: NativeInputAttributes["onBlur"];
+    /** Key-down handler on the `<input>`. Runs before the `onEnter` check; `preventDefault()` skips `onEnter`. */
+    onKeyDown?: NativeInputAttributes["onKeyDown"];
+}
+export interface InputProps extends AriaAttributes, InputNativeProps {
+    /** The native input type. The typed wrappers set it, and apps render a wrapper (`TextInput`). */
+    type: InputType;
+    /** Controlled value. Pass it with `onChange`. */
+    value?: string;
+    /**
+     * Initial value while uncontrolled.
+     * @default ""
+     */
+    defaultValue?: string;
+    /** Called with the new string on every edit and with `""` when the clear button is pressed. */
+    onChange?: (value: string) => void;
+    /** Called with the value when Enter is pressed (not during IME composition, not after `onKeyDown` prevents default). */
+    onEnter?: (value: string) => void;
+    /**
+     * Control rung: 20 / 24 / 32 / 36 / 40px tall.
+     * @default InputSize.MEDIUM
+     */
     size?: InputSize;
-    /** The underlying `<input type>`. Wrappers set it. */
-    type: HTMLInputElement["type"];
-    /** Controlled value. */
-    value?: T;
-    placeholder?: string;
-    /** Decorative icon inside the left edge. Give it `onClick` to make it a button. */
-    leading?: {
-        icon: PhosphorIcon;
-        onClick?: (e: React.MouseEvent<HTMLButtonElement>) => void;
-    };
-    /** Action button inside the right edge — clear, reveal, copy. */
-    trailing?: {
-        icon: PhosphorIcon;
-        onClick: (e: React.MouseEvent<HTMLButtonElement>) => void;
-        isDisabled?: boolean;
-    };
-    /** Label rendered above the field. */
+    /**
+     * Resting fill, from the surface set. Ignored with `isGhost`.
+     * @default InputVariant.PRIMARY
+     */
+    variant?: InputVariant;
+    /**
+     * Ghost field: no fill and no hairline at rest; the frame appears on hover and focus (1.x
+     * `TRANSPARENT`). For fields set into a surface that already frames them (a toolbar, a table cell).
+     * @default false
+     */
+    isGhost?: boolean;
+    /** Label above the field, rendered through `Field`. For anything more, wrap the input in `Field`. */
     label?: string;
-    /** Adds an info icon beside the label with this content on hover. */
-    labelTooltip?: string | React.ReactNode;
-    /** Message shown under the field; also switches the border to the error color. */
+    /** Hint shown while the value is empty. It is never the label. */
+    placeholder?: string;
+    /** Message from the app, shown under the field through `Field`. Also turns the border red and sets `aria-invalid`. */
     error?: string;
-    /** Switches the border to the error color without a message. Implied by `error`. */
+    /**
+     * Error border and `aria-invalid` without a message. `error` implies it.
+     * @default false
+     */
     isError?: boolean;
-    /** Appends the red required asterisk to the label. */
-    isRequired?: boolean;
+    /** Leading Phosphor icon component (`MagnifyingGlassIcon`, not `<MagnifyingGlassIcon />`), sized to the rung. Decorative. */
+    icon?: PhosphorIcon;
+    /** Content at the start of the field, before `icon` (an `Avatar`, a `Beacon`, a `Button`). */
+    leading?: ReactNode;
+    /** Content at the end of the field, after the clear button (a `Button`, a `Kbd` hint). */
+    trailing?: ReactNode;
+    /** Fixed text before the value (`"https://"`). It is not part of the value. */
+    prefix?: string;
+    /** Fixed text after the value (`":5432"`, `"ms"`). It is not part of the value. */
+    suffix?: string;
+    /**
+     * Shows a clear button while the value is non-empty and the field is editable. It calls `onChange("")` and focuses the input.
+     * @default false
+     */
+    isClearable?: boolean;
+    /**
+     * Not focusable or editable. Shows the disabled look.
+     * @default false
+     */
     isDisabled?: boolean;
-    autoFocus?: boolean;
-    /** Numeric bounds — only meaningful when `type` is "number". */
-    min?: number;
-    max?: number;
-    /** Stepper increment. Only meaningful when `type` is "number". */
-    step?: number;
-    onFocus?: (e: React.FocusEvent<HTMLInputElement>) => void;
-    onBlur?: (e: React.FocusEvent<HTMLInputElement>) => void;
-    onKeyDown?: (e: React.KeyboardEvent<HTMLInputElement>) => void;
-    /** A number is px. Ignored when `fillWidth` is set. */
-    width?: number | string;
-    /** Stretch to the parent's width. */
+    /**
+     * Focusable and selectable but not editable. No hover change and no clear button.
+     * @default false
+     */
+    isReadOnly?: boolean;
+    /**
+     * Required marker on the `label` (via `Field`) and `aria-required`. It does no validation.
+     * @default false
+     */
+    isRequired?: boolean;
+    /**
+     * Type family of the value, placeholder, `prefix` and `suffix`. Use mono for IDs, hosts, keys and code.
+     * @default FontFamily.SANS
+     */
+    family?: InputFamily;
+    /**
+     * Stretch to the parent's width. Without it, the field is about 20 characters wide.
+     * @default false
+     */
     fillWidth?: boolean;
-    /** Render the value in the mono family — for IDs, keys, and code. */
-    isMonospace?: boolean;
+    /** Accessible name when there is no visible label (no `label` and no wrapping `Field`). */
+    ariaLabel?: string;
+    /**
+     * DOM id of the `<input>`. A wrapping `Field`'s label points to it.
+     * @default useId()
+     */
+    id?: string;
+    /** Any `data-*` attribute, forwarded to the `<input>`. */
+    [dataAttribute: `data-${string}`]: string | number | boolean | undefined;
+    /** Extra class on the root: the `Field` wrapper when Input renders one, otherwise the frame. */
+    className?: string;
+    /** Inline style on the root; only for setting CSS custom properties. */
+    style?: CSSProperties;
 }
 /**
- * The generic text field every typed input wraps. Renders the label, the field,
- * the leading/trailing affordances and the error line.
- *
- * Prefer a concrete wrapper — `TextInput`, `PasswordInput`, `NumberInput` — which
- * pin `type` and `parse` for you. Use this directly only for a value type none of
- * them cover.
+ * In-field button rung: 20px up to MEDIUM, 24px for LARGE and X_LARGE. Shared with the inputs that
+ * put a button inside Input's frame (PasswordInput, NumberInput, CopyInput).
+ */
+export declare const INPUT_SIZE_TO_BUTTON_SIZE_MAP: Record<InputSize, ButtonSize>;
+/**
+ * The gap between the in-field parts per rung, as a `Space` (the value `INPUT_SIZE_TO_CSS_MAP`
+ * draws). For an input that lays out its own trailing parts beside the clear button (SearchInput).
  */
-declare const Input: <T extends InputValue>(props: InputProps<T> & {
-    ref?: Ref<HTMLInputElement>;
-}) => React.ReactElement;
+export declare const INPUT_SIZE_TO_GAP_MAP: Record<InputSize, Space>;
+/** The single-line text field frame every text-like input wraps. Apps render `TextInput`. */
+declare const Input: import("react").ForwardRefExoticComponent<InputProps & import("react").RefAttributes<HTMLInputElement>>;
 export default Input;