neatkit 0.1.0 → 0.3.0

package/README.md

@@ -2,8 +2,9 @@
   <!-- The media queries determine the image based on website theme -->
   <source media="(prefers-color-scheme: dark)" srcset=".assets/banner/dark-mode.png">
   <source media="(prefers-color-scheme: light)" srcset=".assets/banner/light-mode.png">
-  <!-- Fallback to light mode variant if no match -->
-  <img alt="Neatkit Banner" src=".assets/banner/light-mode.png">
+  <!-- Fallback to light mode variant if no match. The `alt` attribute is
+  intentionally set to a space to prevent rendering if the image is missing -->
+  <img alt=" " src=".assets/banner/light-mode.png">
 </picture>
 
 ######
@@ -11,32 +12,8 @@
 An opinionated React UI library for modern web applications, combining 
 accessible components, a cohesive design system, light and dark themes, accent 
 customization, design tokens, SSR support, strong TypeScript support, and 
-comprehensive documentation. To browse the component library, click 
-[here](https://neatkit.org).
-
-### Getting Started
-
-Install Neatkit with your package manager:
-
-```sh
-npm install neatkit
-```
-
-Import the stylesheet once in your app, then use components wherever you need
-them:
-
-```tsx
-import "neatkit/style.css";
-import { Button } from "neatkit";
-
-export function App() {
-  return (
-    <Button variant="primary" size="md">
-      Get started
-    </Button>
-  );
-}
-```
+comprehensive documentation. To browse the component library and its 
+documentation, click [here](https://neatkit.org).
 
 ### Contributing
 
@@ -49,9 +26,9 @@ To get started, see `CONTRIBUTING.md`.
 
 ### License
 
-This project is licensed under the GPL-3.0 License, reflecting a commitment to
-keeping this software free and open-source. The GPL-3.0 promotes freedom,
-transparency, and collaboration, allowing users to freely use, modify, and
-distribute the software while ensuring it remains community-driven.
+This project is licensed under the Mozilla Public License 2.0 (MPL-2.0), 
+supporting open-source collaboration while allowing use in both open-source 
+and proprietary projects. Modifications to MPL-covered files must remain 
+available under the same license when distributed.
 
 For more details, see `LICENSE.md`.

package/dist/components/Alert/Alert.d.ts

@@ -0,0 +1,29 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+import "./styles/alert.css";
+/** A type representing the semantic color treatment applied to an Alert. */
+export type AlertTone = "info" | "success" | "warning" | "danger";
+/** A type representing properties for the Alert component. */
+export type AlertProps = HTMLAttributes<HTMLDivElement> & {
+    /** The contextual feedback displayed inside the Alert. */
+    children: ReactNode;
+    /** The semantic color treatment applied to the Alert indicator. */
+    tone?: AlertTone;
+};
+/**
+ * Renders a contextual feedback message with a semantic color indicator.
+ *
+ * Alert does not create a live region by default. Consumers can provide a
+ * native role such as `alert` or `status` when feedback requires announcement.
+ *
+ * @param props - The properties that configure the Alert.
+ * @param forwardedReference - The reference assigned to the Alert element.
+ *
+ * @returns The rendered Alert message.
+ */
+declare const Alert: import("react").ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & {
+    /** The contextual feedback displayed inside the Alert. */
+    children: ReactNode;
+    /** The semantic color treatment applied to the Alert indicator. */
+    tone?: AlertTone;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export default Alert;

package/dist/components/Alert/index.d.ts

@@ -0,0 +1,2 @@
+export { default as Alert } from "./Alert";
+export type { AlertProps, AlertTone } from "./Alert";

package/dist/components/Avatar/Avatar.d.ts

@@ -0,0 +1,28 @@
+import { type HTMLAttributes } from "react";
+import "./styles/avatar.css";
+/** A type representing properties for the Avatar component. */
+export type AvatarProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /** The alternative text, or an empty value for a decorative image. */
+    alt?: string;
+    /** The image source displayed until loading fails. */
+    image?: string;
+    /** The CSS-compatible Avatar diameter. */
+    size?: number | string;
+};
+/**
+ * Renders a stable circular image with a deterministic fallback initial.
+ *
+ * @param props - The properties that configure the Avatar.
+ * @param forwardedReference - The reference assigned to the rendered element.
+ *
+ * @returns The rendered Avatar.
+ */
+declare const Avatar: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /** The alternative text, or an empty value for a decorative image. */
+    alt?: string;
+    /** The image source displayed until loading fails. */
+    image?: string;
+    /** The CSS-compatible Avatar diameter. */
+    size?: number | string;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export default Avatar;

package/dist/components/Avatar/index.d.ts

@@ -0,0 +1,2 @@
+export { default as Avatar } from "./Avatar";
+export type { AvatarProps } from "./Avatar";

package/dist/components/Badge/Badge.d.ts

@@ -0,0 +1,32 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+import "./styles/badge.css";
+/** A type representing the visual emphasis applied to a Badge. */
+export type BadgeVariant = "outline" | "soft" | "solid";
+/** A type representing the semantic color treatment applied to a Badge. */
+export type BadgeTone = "neutral" | "info" | "success" | "warning" | "danger";
+/** A type representing properties for the Badge component. */
+export type BadgeProps = HTMLAttributes<HTMLSpanElement> & {
+    /** The label content displayed within the Badge. */
+    children: ReactNode;
+    /** The visual emphasis applied to the Badge. */
+    variant?: BadgeVariant;
+    /** The semantic color treatment applied to the Badge. */
+    tone?: BadgeTone;
+};
+/**
+ * Renders a compact, non-interactive classification or status label.
+ *
+ * @param props - The properties that configure the Badge.
+ * @param forwardedReference - The reference assigned to the rendered element.
+ *
+ * @returns The rendered Badge.
+ */
+declare const Badge: import("react").ForwardRefExoticComponent<HTMLAttributes<HTMLSpanElement> & {
+    /** The label content displayed within the Badge. */
+    children: ReactNode;
+    /** The visual emphasis applied to the Badge. */
+    variant?: BadgeVariant;
+    /** The semantic color treatment applied to the Badge. */
+    tone?: BadgeTone;
+} & import("react").RefAttributes<HTMLSpanElement>>;
+export default Badge;

package/dist/components/Badge/index.d.ts

@@ -0,0 +1,2 @@
+export { default as Badge } from "./Badge";
+export type { BadgeProps, BadgeTone, BadgeVariant } from "./Badge";

package/dist/components/Button/Button.d.ts

@@ -1,11 +1,61 @@
-import type { ButtonHTMLAttributes, ReactNode } from "react";
-import "./Button.css";
+import { type ComponentPropsWithRef, type ComponentPropsWithoutRef, type ElementType, type ReactElement, type ReactNode } from "react";
+import { type IconType } from "../Icon";
+import "./styles/button.css";
+/** A type representing the visual treatment of a Button. */
 export type ButtonVariant = "primary" | "secondary" | "ghost";
-export type ButtonSize = "sm" | "md" | "lg";
-export type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
-    children: ReactNode;
+/** A type representing the semantic intent applied to a Button. */
+export type ButtonTone = "info" | "success" | "warning" | "danger";
+/** A type representing the outline shape of a Button. */
+export type ButtonShape = "rectangle" | "capsule";
+/** A type representing the placement of a Button icon. */
+export type ButtonIconAlignment = "left" | "right";
+/** A type representing the horizontal alignment of Button contents. */
+export type ButtonTextAlignment = "left" | "center" | "right";
+/** A type representing Button-specific properties. */
+type ButtonOwnProps = {
+    /** The content displayed inside the Button. */
+    children?: ReactNode;
+    /** The visual treatment applied to the Button. */
     variant?: ButtonVariant;
-    size?: ButtonSize;
+    /** The semantic intent applied to the Button. */
+    tone?: ButtonTone;
+    /** The outline shape applied to the Button. */
+    shape: ButtonShape;
+    /** Whether the Button fills its containing block. */
+    fullWidth?: boolean;
+    /** Whether the Button displays a loading indicator and blocks interaction. */
+    loading?: boolean;
+    /** Whether the Button blocks user interaction. */
+    disabled?: boolean;
+    /**
+     * The icon displayed alongside the Button content.
+     *
+     * @warning When no children are provided, set `aria-label` or
+     * `aria-labelledby` to describe the action to assistive technology.
+     */
+    icon?: IconType;
+    /** The side of the content where the icon is displayed. */
+    iconAlignment?: ButtonIconAlignment;
+    /** The horizontal alignment applied to the Button contents. */
+    textAlignment?: ButtonTextAlignment;
 };
-export declare function Button({ children, className, size, type, variant, ...props }: ButtonProps): import("react").JSX.Element;
-//# sourceMappingURL=Button.d.ts.map
+/** A type representing the reference accepted by a polymorphic element. */
+type ButtonReference<Component extends ElementType> = ComponentPropsWithRef<Component>["ref"];
+/** A type representing properties for a polymorphic Button element. */
+export type ButtonProps<Component extends ElementType = "button"> = ButtonOwnProps & {
+    as?: Component;
+} & Omit<ComponentPropsWithoutRef<Component>, keyof ButtonOwnProps | "as">;
+/** A type representing the public polymorphic Button component. */
+type ButtonComponent = <Component extends ElementType = "button">(props: ButtonProps<Component> & {
+    ref?: ButtonReference<Component>;
+}) => ReactElement | null;
+/**
+ * Renders an action control with visual, loading, and polymorphic options.
+ *
+ * @param props - The properties that configure the Button.
+ * @param forwardedReference - The reference assigned to the rendered element.
+ *
+ * @returns The rendered Button element.
+ */
+declare const Button: ButtonComponent;
+export default Button;

package/dist/components/Button/index.d.ts

@@ -1,3 +1,2 @@
-export { Button } from "./Button";
-export type { ButtonProps } from "./Button";
-//# sourceMappingURL=index.d.ts.map
+export { default as Button } from "./Button";
+export type { ButtonIconAlignment, ButtonProps, ButtonShape, ButtonTextAlignment, ButtonTone, ButtonVariant, } from "./Button";

package/dist/components/Card/Card.d.ts

@@ -0,0 +1,40 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+import "./styles/card.css";
+/** A type representing the optional labels displayed in a Card header. */
+export type CardHeader = {
+    /** The primary label displayed in the Card header. */
+    title: string;
+    /** The secondary label displayed after the primary label. */
+    subtitle?: string;
+};
+/** A type representing the internal spacing applied by a Card. */
+export type CardSpacing = "none" | "standard";
+/** A type representing properties for the Card component. */
+export type CardProps = HTMLAttributes<HTMLDivElement> & {
+    /** The content displayed inside the Card. */
+    children: ReactNode;
+    /** The optional fixed-format labels displayed above the Card content. */
+    header?: CardHeader;
+    /** The internal spacing applied to the Card content region. */
+    spacing?: CardSpacing;
+};
+/**
+ * Renders a bordered surface for grouping related content.
+ *
+ * A header moves spacing into a private content region beneath its labels.
+ * Spacing can be removed for custom full-bleed layouts.
+ *
+ * @param props - The properties that configure the Card.
+ * @param forwardedReference - The reference assigned to the Card element.
+ *
+ * @returns The rendered Card surface.
+ */
+declare const Card: import("react").ForwardRefExoticComponent<HTMLAttributes<HTMLDivElement> & {
+    /** The content displayed inside the Card. */
+    children: ReactNode;
+    /** The optional fixed-format labels displayed above the Card content. */
+    header?: CardHeader;
+    /** The internal spacing applied to the Card content region. */
+    spacing?: CardSpacing;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export default Card;

package/dist/components/Card/index.d.ts

@@ -0,0 +1,2 @@
+export { default as Card } from "./Card";
+export type { CardHeader, CardProps, CardSpacing, } from "./Card";

package/dist/components/Checkbox/Checkbox.d.ts

@@ -0,0 +1,35 @@
+import { type CSSProperties, type InputHTMLAttributes, type ReactNode } from "react";
+import "./styles/checkbox.css";
+/** A type representing properties for the Checkbox component. */
+export type CheckboxProps = Omit<InputHTMLAttributes<HTMLInputElement>, "children" | "className" | "style" | "type"> & {
+    /** The optional clickable and accessible label for the Checkbox. */
+    children?: ReactNode;
+    /** The additional class name applied to the Checkbox label root. */
+    className?: string;
+    /** Whether the Checkbox exposes an invalid semantic and visual state. */
+    invalid?: boolean;
+    /** The inline styles applied to the Checkbox label root. */
+    style?: CSSProperties;
+};
+/**
+ * Renders a labelled native form choice.
+ *
+ * Checkbox represents a form choice, while Switch represents an immediate
+ * change between two settings.
+ *
+ * @param props - The properties that configure the Checkbox.
+ * @param forwardedReference - The reference assigned to the native input.
+ *
+ * @returns The rendered Checkbox control.
+ */
+declare const Checkbox: import("react").ForwardRefExoticComponent<Omit<InputHTMLAttributes<HTMLInputElement>, "className" | "style" | "children" | "type"> & {
+    /** The optional clickable and accessible label for the Checkbox. */
+    children?: ReactNode;
+    /** The additional class name applied to the Checkbox label root. */
+    className?: string;
+    /** Whether the Checkbox exposes an invalid semantic and visual state. */
+    invalid?: boolean;
+    /** The inline styles applied to the Checkbox label root. */
+    style?: CSSProperties;
+} & import("react").RefAttributes<HTMLInputElement>>;
+export default Checkbox;

package/dist/components/Checkbox/index.d.ts

@@ -0,0 +1,2 @@
+export { default as Checkbox } from "./Checkbox";
+export type { CheckboxProps } from "./Checkbox";

package/dist/components/CheckboxGroup/CheckboxGroup.d.ts

@@ -0,0 +1,62 @@
+import { type ChangeEventHandler, type HTMLAttributes, type ReactNode } from "react";
+import "./styles/checkbox-group.css";
+/** A type representing the visual direction of Checkbox options. */
+export type CheckboxGroupOrientation = "horizontal" | "vertical";
+/** A type representing properties for the CheckboxGroup component. */
+export type CheckboxGroupProps = Omit<HTMLAttributes<HTMLDivElement>, "children" | "defaultValue" | "onChange"> & {
+    /**
+     * The direct Checkbox options or fragments belonging to the group.
+     *
+     * CheckboxGroup owns each option's checked, defaultChecked, and name state.
+     */
+    children: ReactNode;
+    /** The initially selected values for uncontrolled usage. */
+    defaultValue?: readonly string[];
+    /** Whether every Checkbox in the group is disabled. */
+    disabled?: boolean;
+    /** Whether the group exposes an invalid semantic and visual state. */
+    invalid?: boolean;
+    /** The native form name shared by every Checkbox in the group. */
+    name: string;
+    /** The native change callback invoked by Checkbox selection. */
+    onChange?: ChangeEventHandler<HTMLInputElement>;
+    /** The direction in which Checkbox options are arranged. */
+    orientation?: CheckboxGroupOrientation;
+    /** Whether the group requires at least one enabled selected option. */
+    required?: boolean;
+    /** The selected values for controlled usage. */
+    value?: readonly string[];
+};
+/**
+ * Renders a native Checkbox group with shared form and validation state.
+ *
+ * @param props - The properties that configure the CheckboxGroup.
+ * @param forwardedReference - The reference assigned to the group root.
+ *
+ * @returns The rendered CheckboxGroup.
+ */
+declare const CheckboxGroup: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "defaultValue" | "children" | "onChange"> & {
+    /**
+     * The direct Checkbox options or fragments belonging to the group.
+     *
+     * CheckboxGroup owns each option's checked, defaultChecked, and name state.
+     */
+    children: ReactNode;
+    /** The initially selected values for uncontrolled usage. */
+    defaultValue?: readonly string[];
+    /** Whether every Checkbox in the group is disabled. */
+    disabled?: boolean;
+    /** Whether the group exposes an invalid semantic and visual state. */
+    invalid?: boolean;
+    /** The native form name shared by every Checkbox in the group. */
+    name: string;
+    /** The native change callback invoked by Checkbox selection. */
+    onChange?: ChangeEventHandler<HTMLInputElement>;
+    /** The direction in which Checkbox options are arranged. */
+    orientation?: CheckboxGroupOrientation;
+    /** Whether the group requires at least one enabled selected option. */
+    required?: boolean;
+    /** The selected values for controlled usage. */
+    value?: readonly string[];
+} & import("react").RefAttributes<HTMLDivElement>>;
+export default CheckboxGroup;

package/dist/components/CheckboxGroup/contexts/CheckboxGroupContext.d.ts

@@ -0,0 +1,22 @@
+import { type ChangeEvent } from "react";
+/** A type representing state shared by CheckboxGroup with each Checkbox. */
+export type CheckboxGroupContextValue = {
+    /** The initial selected values for an uncontrolled group. */
+    defaultValue: readonly string[];
+    /** Whether every Checkbox in the group is disabled. */
+    disabled: boolean;
+    /** Handles a native Checkbox change at group scope. */
+    handleChange: (event: ChangeEvent<HTMLInputElement>) => void;
+    /** Whether the group currently contains a selected value. */
+    hasSelection: boolean;
+    /** The native form name shared by every Checkbox. */
+    name: string;
+    /** Whether the group requires at least one selected value. */
+    required: boolean;
+    /** The selected values for a controlled group. */
+    value?: readonly string[];
+    /** The option acting as the native group-validation anchor. */
+    validationValue?: string;
+};
+/** The internal React context connecting CheckboxGroup and Checkbox. */
+export declare const CheckboxGroupContext: import("react").Context<CheckboxGroupContextValue | undefined>;

package/dist/components/CheckboxGroup/hooks/useCheckboxGroup.d.ts

@@ -0,0 +1,7 @@
+import { type CheckboxGroupContextValue } from "../contexts/CheckboxGroupContext";
+/**
+ * Returns the optional CheckboxGroup state surrounding a Checkbox.
+ *
+ * @returns The nearest CheckboxGroup context value when one exists.
+ */
+export declare function useCheckboxGroup(): CheckboxGroupContextValue | undefined;

package/dist/components/CheckboxGroup/index.d.ts

@@ -0,0 +1,2 @@
+export { default as CheckboxGroup } from "./CheckboxGroup";
+export type { CheckboxGroupOrientation, CheckboxGroupProps, } from "./CheckboxGroup";

package/dist/components/Content/Content.d.ts

@@ -0,0 +1,58 @@
+import { type ComponentPropsWithRef, type ComponentPropsWithoutRef, type CSSProperties, type ElementType, type ReactElement } from "react";
+import "./styles/content.css";
+/** A type representing the explicit themes supported by Content. */
+export type ContentTheme = "light" | "dark";
+/** A type representing Content's visual background modes. */
+export type ContentMode = "grid" | "none";
+/** A type representing Content's minimum-height behavior. */
+export type ContentFill = "none" | "available" | "viewport";
+/** A type representing Content's vertical spacing behavior. */
+export type ContentSpacing = "standard" | "none";
+/** A type representing CSS custom properties accepted by Content styles. */
+type ContentCustomProperties = {
+    [CustomProperty in `--${string}`]?: string | number;
+};
+/** A type representing native Content styles and CSS custom properties. */
+type ContentStyle = CSSProperties & ContentCustomProperties;
+/** A type representing the reference accepted by a polymorphic element. */
+type ContentReference<Component extends ElementType> = ComponentPropsWithRef<Component>["ref"];
+/** A type representing properties owned by the Content component. */
+type ContentOwnProps = {
+    /** The explicit color theme applied within Content. */
+    theme?: ContentTheme;
+    /** The accent color exposed to Content descendants. */
+    accent?: string;
+    /** The visual background treatment applied to Content. */
+    mode?: ContentMode;
+    /** The minimum-height behavior applied to Content. */
+    fill?: ContentFill;
+    /** The vertical spacing applied within Content. */
+    spacing?: ContentSpacing;
+    /** Whether Content applies its responsive cell-aligned inner width. */
+    constrain?: boolean;
+};
+/** A type representing properties for a polymorphic Content element. */
+export type ContentProps<Component extends ElementType = "div"> = ContentOwnProps & {
+    as?: Component;
+    style?: ContentStyle;
+} & Omit<ComponentPropsWithoutRef<Component>, keyof ContentOwnProps | "as" | "style">;
+/**
+ * A type representing the public polymorphic Content component.
+ *
+ * @param props - The properties accepted by the selected element.
+ *
+ * @returns The rendered Content element.
+ */
+type ContentComponent = <Component extends ElementType = "div">(props: ContentProps<Component> & {
+    ref?: ContentReference<Component>;
+}) => ReactElement | null;
+/**
+ * Renders a scoped Neatkit design-system boundary.
+ *
+ * @param props - The properties that configure Content and its root element.
+ * @param forwardedReference - The reference assigned to the root element.
+ *
+ * @returns The rendered Content element.
+ */
+declare const Content: ContentComponent;
+export default Content;

package/dist/components/Content/hooks/useContentLayout.d.ts

@@ -0,0 +1,18 @@
+import { type ForwardedRef, type RefCallback } from "react";
+/** A type representing Content's measured layout state. */
+type ContentLayout = {
+    /** The callback ref assigned to the Content root. */
+    rootReference: RefCallback<HTMLElement>;
+    /** The enhanced inner width, or undefined while CSS controls sizing. */
+    innerWidth: number | undefined;
+};
+/**
+ * Measures a Content root and progressively enhances its inner width.
+ *
+ * @param forwardedReference - The public reference assigned to the root.
+ * @param constrain - Whether responsive inner-width sizing is enabled.
+ *
+ * @returns The merged root reference and calculated inner width.
+ */
+export declare function useContentLayout(forwardedReference: ForwardedRef<HTMLElement>, constrain: boolean): ContentLayout;
+export {};

package/dist/components/Content/index.d.ts

@@ -0,0 +1,2 @@
+export { default as Content } from "./Content";
+export type { ContentFill, ContentMode, ContentProps, ContentSpacing, ContentTheme, } from "./Content";

package/dist/components/Content/utils/layout.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Calculates the enhanced inner width for a Content root.
+ *
+ * Provides a centered cell-aligned width for eligible container sizes.
+ *
+ * @param availableWidth - The Content root's available content-box width.
+ * @param cellSize - The resolved grid cell size in CSS pixels.
+ *
+ * @returns The cell-aligned width, or undefined when CSS controls sizing.
+ */
+export declare function calculateContentInnerWidth(availableWidth: number, cellSize: number): number | undefined;

package/dist/components/Divider/Divider.d.ts

@@ -0,0 +1,30 @@
+import { type HTMLAttributes } from "react";
+import "./styles/divider.css";
+/** A type representing the direction of a Divider. */
+export type DividerOrientation = "horizontal" | "vertical";
+/** A type representing properties for the Divider component. */
+export type DividerProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /** The direction in which the separator is drawn. */
+    orientation?: DividerOrientation;
+    /** Whether the separator is hidden from assistive technology. */
+    decorative?: boolean;
+    /** The optional label displayed within a horizontal separator. */
+    text?: string;
+};
+/**
+ * Renders a semantic or decorative separator.
+ *
+ * @param props - The properties that configure the Divider.
+ * @param forwardedReference - The reference assigned to the rendered element.
+ *
+ * @returns The rendered Divider.
+ */
+declare const Divider: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /** The direction in which the separator is drawn. */
+    orientation?: DividerOrientation;
+    /** Whether the separator is hidden from assistive technology. */
+    decorative?: boolean;
+    /** The optional label displayed within a horizontal separator. */
+    text?: string;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export default Divider;

package/dist/components/Divider/index.d.ts

@@ -0,0 +1,2 @@
+export { default as Divider } from "./Divider";
+export type { DividerOrientation, DividerProps } from "./Divider";

package/dist/components/Field/Field.d.ts

@@ -0,0 +1,61 @@
+import { type AriaAttributes, type HTMLAttributes, type ReactElement, type ReactNode } from "react";
+import "./styles/field.css";
+/** A type representing the label placement used by a Field. */
+export type FieldOrientation = "horizontal" | "vertical";
+/** A type representing properties accepted by a Field control. */
+type FieldControlProps = {
+    /** The identifiers describing the control. */
+    "aria-describedby"?: string;
+    /** The identifiers naming the control. */
+    "aria-labelledby"?: string;
+    /** The validation state exposed by the control. */
+    "aria-invalid"?: AriaAttributes["aria-invalid"];
+    /** Whether the control blocks interaction. */
+    disabled?: boolean;
+    /** The identifier associated with the Field label. */
+    id?: string;
+    /** Whether the control requires a value. */
+    required?: boolean;
+};
+/** A type representing properties for the Field component. */
+export type FieldProps = Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /** The single control described by the Field. */
+    children: ReactElement<FieldControlProps>;
+    /** The optional help content describing the control. */
+    description?: ReactNode;
+    /** Whether the Field disables its control. */
+    disabled?: boolean;
+    /** The optional validation message describing an invalid control. */
+    error?: ReactNode;
+    /** The optional visible label associated with the control. */
+    label?: ReactNode;
+    /** The placement of the label relative to the control. */
+    orientation?: FieldOrientation;
+    /** Whether the Field requires the consumer to provide a value. */
+    required?: boolean;
+};
+/**
+ * Renders a labelled control with shared description and validation semantics.
+ *
+ * @param props - The properties that configure the Field and its control.
+ * @param forwardedReference - The reference assigned to the Field container.
+ *
+ * @returns The rendered Field and associated control.
+ */
+declare const Field: import("react").ForwardRefExoticComponent<Omit<HTMLAttributes<HTMLDivElement>, "children"> & {
+    /** The single control described by the Field. */
+    children: ReactElement<FieldControlProps>;
+    /** The optional help content describing the control. */
+    description?: ReactNode;
+    /** Whether the Field disables its control. */
+    disabled?: boolean;
+    /** The optional validation message describing an invalid control. */
+    error?: ReactNode;
+    /** The optional visible label associated with the control. */
+    label?: ReactNode;
+    /** The placement of the label relative to the control. */
+    orientation?: FieldOrientation;
+    /** Whether the Field requires the consumer to provide a value. */
+    required?: boolean;
+} & import("react").RefAttributes<HTMLDivElement>>;
+export default Field;

package/dist/components/Field/index.d.ts

@@ -0,0 +1,2 @@
+export { default as Field } from "./Field";
+export type { FieldOrientation, FieldProps } from "./Field";