@photonix/basic 3.0.0 → 3.1.0

package/dist/index.d.ts

@@ -1,6 +1,7 @@
 import * as React from 'react';
 import React__default from 'react';
 export * from '@photonix/icons';
+import * as react_jsx_runtime from 'react/jsx-runtime';
 
 /**
  * Layout component type definitions
@@ -565,6 +566,8 @@ interface CheckboxProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElemen
      * Whether the checkbox is checked (controlled)
      */
     checked?: boolean;
+    /** Participate in native form validation. */
+    required?: boolean;
     /**
      * Initial checked state when uncontrolled
      */
@@ -603,6 +606,8 @@ interface RadioProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>,
      * Whether the radio is selected (controlled)
      */
     checked?: boolean;
+    /** Participate in native form validation. */
+    required?: boolean;
     /**
      * Initial selected state when uncontrolled
      */
@@ -622,11 +627,42 @@ interface RadioProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>,
 }
 declare const Radio: React.ForwardRefExoticComponent<RadioProps & React.RefAttributes<HTMLButtonElement>>;
 
+/** Props shared by RadioGroup and CheckboxGroup so the two groups read the same way. */
+interface SelectionGroupBaseProps extends Omit<React.FieldsetHTMLAttributes<HTMLFieldSetElement>, 'onChange' | 'defaultValue' | 'value' | 'form' | 'name'> {
+    /** Visible group label (legend). Omit only when `aria-label` names the group. */
+    label?: React.ReactNode;
+    /** Supporting text below the label. */
+    description?: React.ReactNode;
+    /** Error message; also marks the group invalid. */
+    error?: React.ReactNode;
+    /** Form field name applied to every option. */
+    name?: string;
+    /** Associates the options with a form outside the group. */
+    form?: string;
+    disabled?: boolean;
+    required?: boolean;
+    /** Layout of the options. @default 'vertical' */
+    orientation?: 'horizontal' | 'vertical';
+    children: React.ReactNode;
+}
+
+interface RadioGroupProps extends SelectionGroupBaseProps {
+    /** Selected option value (controlled). */
+    value?: string;
+    /** Initially selected option value (uncontrolled). */
+    defaultValue?: string;
+    onChange?: (value: string) => void;
+}
+/** Single-choice group of `Radio` children with roving focus and native form support. */
+declare const RadioGroup: React.ForwardRefExoticComponent<RadioGroupProps & React.RefAttributes<HTMLFieldSetElement>>;
+
 interface SwitchProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'onChange'> {
     /**
      * Whether the switch is on (controlled)
      */
     checked?: boolean;
+    /** Participate in native form validation. */
+    required?: boolean;
     /**
      * Initial state when uncontrolled
      */
@@ -662,6 +698,8 @@ interface TextFieldDropdownOption {
     disabled?: boolean;
 }
 interface TextFieldProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'onChange' | 'size'> {
+    /** Style the native input without changing the field wrapper layout. */
+    inputStyle?: React.CSSProperties;
     /** Label text. */
     label?: string;
     /** Whether the label is placed inside or outside the input box. Default is 'outside'. */
@@ -1002,7 +1040,12 @@ interface ChipProps extends React.HTMLAttributes<HTMLDivElement> {
     /**
      * Size of the chip
      */
-    size?: 'medium' | 'large';
+    size?: 'small' | 'medium' | 'large';
+    /**
+     * Corner shape: 'pill' is fully rounded, 'rounded' uses the Button corner
+     * radius (e.g. tags inside an input).
+     */
+    shape?: 'pill' | 'rounded';
     /**
      * Whether the chip is disabled
      */
@@ -1017,6 +1060,16 @@ interface ChipProps extends React.HTMLAttributes<HTMLDivElement> {
      * Callback when clear button is clicked (only for filled + hasDropdown)
      */
     onClear?: (e: React.MouseEvent) => void;
+    /**
+     * Shows the chip's delete button (CancelFilled) on any variant, e.g. for
+     * removable tags. Takes precedence over `actionIcon`.
+     */
+    onRemove?: (e: React.MouseEvent) => void;
+    /**
+     * Accessible label for the close button
+     * @default `Remove ${label}`
+     */
+    removeLabel?: string;
     /**
      * Optional action icon shown after the dropdown affordance
      */
@@ -1106,4 +1159,208 @@ declare const LayoutProvider: React.FC<LayoutProviderProps>;
  */
 declare const useLayout: () => LayoutContextValue | null;
 
-export { AVATAR_IMAGES, AspectRatio$1 as AspectRatio, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, AvatarTemplate, type AvatarTemplateProps, type BackgroundToken, Badge, Box, Button, type ButtonProps, Center, Checkbox, Chip, ChipBar, type ChipProps, Cluster, Container, CustomScrollbar, Divider, Flex, Grid, GridItem, HStack, Heading, IconButton, Image, LayoutContext, LayoutProvider, Portal, Radio, type RadioProps, type RadiusToken, type ShadowToken, SimpleGrid, Skeleton, SlotPlaceholder, type SlotPlaceholderProps, Spacer, type SpacingToken, Spinner, Stack, Switch, type SwitchProps, Text, TextArea, type TextAreaProps, TextField, type TextFieldDropdownOption, type TextFieldProps, VStack, VisuallyHidden, useLayout };
+/** Native fieldset with a legend, supporting text and an error message for grouped controls. */
+interface FieldsetProps extends React.FieldsetHTMLAttributes<HTMLFieldSetElement> {
+    /** Visible group label. Omit only when the group is named with aria-label. */
+    legend?: React.ReactNode;
+    description?: React.ReactNode;
+    error?: React.ReactNode;
+}
+declare const Fieldset: React.ForwardRefExoticComponent<FieldsetProps & React.RefAttributes<HTMLFieldSetElement>>;
+
+interface CheckboxGroupProps extends SelectionGroupBaseProps {
+    /** Checked option values (controlled). */
+    value?: string[];
+    /** Initially checked option values (uncontrolled). */
+    defaultValue?: string[];
+    onChange?: (value: string[]) => void;
+    /** Message shown by native validation when `required` and nothing is checked. */
+    requiredMessage?: string;
+}
+declare const CheckboxGroupContext: React.Context<{
+    value: string[];
+    name?: string;
+    form?: string;
+    disabled?: boolean;
+    toggle: (value: string, checked: boolean) => void;
+} | null>;
+/** Multi-choice group of `Checkbox` children; same API shape as `RadioGroup`. */
+declare const CheckboxGroup: React.ForwardRefExoticComponent<CheckboxGroupProps & React.RefAttributes<HTMLFieldSetElement>>;
+
+interface NumberFieldProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "value" | "defaultValue" | "onChange" | "type" | "min" | "max" | "step" | "size"> {
+    label: string;
+    size?: "small" | "medium" | "large";
+    inputWidth?: number | string;
+    value?: number | null;
+    defaultValue?: number | null;
+    onChange?: (value: number | null) => void;
+    min?: number;
+    max?: number;
+    step?: number;
+    error?: string;
+    description?: string;
+    /** Accessible name of the decrement button. @default `Decrease ${label}` */
+    decreaseLabel?: string;
+    /** Accessible name of the increment button. @default `Increase ${label}` */
+    increaseLabel?: string;
+}
+declare function NumberField({ label, size, inputWidth, value, defaultValue, onChange, min, max, step, error, description, disabled, readOnly, name, decreaseLabel, increaseLabel, ...props }: NumberFieldProps): react_jsx_runtime.JSX.Element;
+
+interface RatingProps {
+    label: string;
+    value?: number;
+    defaultValue?: number;
+    max?: number;
+    onChange?: (value: number) => void;
+    disabled?: boolean;
+    readOnly?: boolean;
+    name?: string;
+    form?: string;
+    /** Show a button that resets the rating to 0. @default false */
+    clearable?: boolean;
+    /** Visible text of the clear button. */
+    clearText?: string;
+    /** Accessible name of the clear button. */
+    clearLabel?: string;
+    /** Accessible name of each star. */
+    getStarLabel?: (value: number, max: number) => string;
+}
+declare function Rating({ label, value, defaultValue, max, onChange, disabled, readOnly, name, form, clearable, clearText, clearLabel, getStarLabel, }: RatingProps): react_jsx_runtime.JSX.Element;
+
+interface OTPProps {
+    label: string;
+    length?: number;
+    /** Insert a visual dash between groups of digits. */
+    groupSize?: number;
+    /** Conceal each entered digit with a dot. Used by PIN. */
+    masked?: boolean;
+    /** Use the label only as an accessible name, without displaying it. */
+    hideLabel?: boolean;
+    /** Render circular PIN indicators instead of rectangular input fields. */
+    dotFields?: boolean;
+    size?: "small" | "medium" | "large";
+    value?: string;
+    defaultValue?: string;
+    onChange?: (value: string) => void;
+    /** Called automatically when every cell is filled. Verify the code here and pass failures via error. */
+    onComplete?: (value: string) => void;
+    disabled?: boolean;
+    /** Display an existing code without edits. Copying a cell copies the full code. */
+    readOnly?: boolean;
+    required?: boolean;
+    name?: string;
+    form?: string;
+    /** Supporting text below the inputs; an error takes precedence. */
+    helperText?: string;
+    error?: string;
+    /** Accessible name of each cell. */
+    getCellLabel?: (label: string, position: number, length: number) => string;
+    /**
+     * Sequential entry, used by PIN: every tap, focus or key lands on the first empty
+     * cell — digits fill left to right, Backspace clears from the right and no cell
+     * can be picked by hand.
+     */
+    sequential?: boolean;
+    /** Focus the field when it mounts (on the next cell when `sequential`). */
+    autoFocus?: boolean;
+}
+/** Segmented numeric entry with independent input cells, paste/autofill and native form support. */
+declare function OTP({ label, length, groupSize, masked, hideLabel, dotFields, size, value, defaultValue, onChange, onComplete, disabled, readOnly, required, name, form, helperText, error, getCellLabel, sequential, autoFocus, }: OTPProps): react_jsx_runtime.JSX.Element;
+
+interface PINProps extends Omit<OTPProps, "label" | "masked" | "hideLabel" | "dotFields" | "groupSize" | "readOnly" | "size"> {
+    /** Number of digits in the PIN. @default 4 */
+    length?: number;
+    /** Accessible name for the PIN inputs; no visible label is rendered. */
+    "aria-label"?: string;
+    /** Focus the first empty dot on mount. Only one field on a page can; pass `false` for the rest. @default true */
+    autoFocus?: boolean;
+}
+/**
+ * Numeric PIN entry with empty circular indicators that fill as digits are entered.
+ * Entry is sequential: digits fill left to right, Backspace clears from the right and
+ * no dot can be picked by hand.
+ */
+declare function PIN({ length, "aria-label": accessibleLabel, autoFocus, ...props }: PINProps): react_jsx_runtime.JSX.Element;
+
+interface EmptyProps {
+    title?: string;
+    description?: React.ReactNode;
+    icon?: React.ReactNode;
+    action?: React.ReactNode;
+}
+declare function Empty({ title, description, icon, action, }: EmptyProps): react_jsx_runtime.JSX.Element;
+
+interface ResultProps {
+    status: "success" | "error" | "warning" | "info";
+    title: string;
+    description?: React.ReactNode;
+    action?: React.ReactNode;
+}
+declare function Result({ status, title, description, action }: ResultProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * How each label/value pair is laid out (Figma "Detail Field"):
+ * - `stack`: label above the value (Detail Field Stack).
+ * - `inline`: label on the left, value right-aligned on the same row (Detail Field Inline).
+ * - `column`: label and value in a 2 : 3 column grid, value left-aligned (Detail Field Column).
+ */
+type DataListLayout = "stack" | "inline" | "column";
+/**
+ * Per-item variant (Figma Detail Field `variant`).
+ * - `normal`: default row.
+ * - `emphasize`: value in medium weight.
+ * - `total`: summary row — emphasized label and value.
+ * - `flexible` (inline/column): the label hugs its text and the value takes the remaining width.
+ * - `hero` (stack): the value as a large headline figure, e.g. a balance; supports `masked`.
+ * - `complex` (stack): a rich value (avatar, title, meta) that fills the row, with the action at the end.
+ */
+type DataListItemVariant = "normal" | "emphasize" | "total" | "flexible" | "hero" | "complex";
+interface DataListItem {
+    id: string;
+    label: React.ReactNode;
+    value: React.ReactNode;
+    /** @default "normal" */
+    variant?: DataListItemVariant;
+    /**
+     * Medium-weight label (Figma Label `emphasized`): primary text. With `labelLead` the label
+     * stays secondary and only takes the weight (`subEmphasized`). Implied by `variant="total"`.
+     */
+    labelEmphasized?: boolean;
+    /** Lead-in before the label in primary text, e.g. "Send to" (Figma Label `subNormal`/`subEmphasized`). */
+    labelLead?: React.ReactNode;
+    /** Icon before the label, 20px (Figma Label `hasPrefix`). */
+    labelIcon?: React.ReactNode;
+    /** Secondary text at the end of the label row, e.g. "20/500" (Figma Label `hasTrailing`). */
+    labelTrailing?: React.ReactNode;
+    /** 20px icon before the value (Figma Body `leadingIcon`). */
+    icon?: React.ReactNode;
+    /** Muted text before the value, e.g. a currency symbol. */
+    valuePrefix?: React.ReactNode;
+    /** `hero` only: replace the figure with six dots (Figma Balance `hidden`). */
+    masked?: boolean;
+    /** Secondary text on a second line under the value (Figma Body `2 line`). */
+    description?: React.ReactNode;
+    /** Status badge (Figma Body `text w badge`), e.g. `<Badge shape="rounded" color="onLight" />`. */
+    badge?: React.ReactNode;
+    /** `inline`: right after the value, 8px apart. `below`: on its own line under the value. @default "inline" */
+    badgePlacement?: "inline" | "below";
+    /**
+     * Control after the value, e.g. a copy IconButton (Figma Body `trailingIcon`, 20px). It sits in a
+     * 20px slot and never grows the row; use `size="medium"` so the button's icon is 20px.
+     */
+    action?: React.ReactNode;
+}
+interface DataListProps {
+    items: DataListItem[];
+    /** Accessible name of the list. @default "Details" */
+    label?: string;
+    /** @default "stack" for `orientation="vertical"`, otherwise "inline" */
+    layout?: DataListLayout;
+    /** Label size (Figma Label `size`): `sm` = title-sm, `lg` = title-md. @default "sm" in stack, "lg" otherwise */
+    labelSize?: "sm" | "lg";
+    /** @deprecated Use `layout`: "horizontal" maps to `inline`, "vertical" to `stack`. */
+    orientation?: "horizontal" | "vertical";
+}
+declare function DataList({ items, label, layout, labelSize, orientation, }: DataListProps): react_jsx_runtime.JSX.Element;
+
+export { AVATAR_IMAGES, AspectRatio$1 as AspectRatio, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, AvatarTemplate, type AvatarTemplateProps, type BackgroundToken, Badge, Box, Button, type ButtonProps, Center, Checkbox, CheckboxGroup, CheckboxGroupContext, type CheckboxGroupProps, Chip, ChipBar, type ChipProps, Cluster, Container, CustomScrollbar, DataList, type DataListItem, type DataListItemVariant, type DataListLayout, type DataListProps, Divider, Empty, type EmptyProps, Fieldset, type FieldsetProps, Flex, Grid, GridItem, HStack, Heading, IconButton, Image, LayoutContext, LayoutProvider, NumberField, type NumberFieldProps, OTP, type OTPProps, PIN, type PINProps, Portal, Radio, RadioGroup, type RadioGroupProps, type RadioProps, type RadiusToken, Rating, type RatingProps, Result, type ResultProps, type ShadowToken, SimpleGrid, Skeleton, SlotPlaceholder, type SlotPlaceholderProps, Spacer, type SpacingToken, Spinner, Stack, Switch, type SwitchProps, Text, TextArea, type TextAreaProps, TextField, type TextFieldDropdownOption, type TextFieldProps, VStack, VisuallyHidden, useLayout };