@kb.ui/react 0.0.0-stage → 0.10.2

package/dist/check-versions.js

@@ -0,0 +1,34 @@
+// scripts/check-versions.ts
+import { realpathSync } from "node:fs";
+import { readdir, readFile } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+async function checkVersions(root) {
+  const scope = join(root, "node_modules", "@kb.ui");
+  const names = await readdir(scope);
+  if (!names.includes("react"))
+    throw new Error("Missing @kb.ui/react");
+  const versions = await Promise.all(names.map(async (name) => {
+    const pkg = JSON.parse(await readFile(join(scope, name, "package.json"), "utf8"));
+    if (typeof pkg !== "object" || pkg === null || !("name" in pkg) || pkg.name !== `@kb.ui/${name}` || !("version" in pkg) || typeof pkg.version !== "string" || !/^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*)(?:\.(?:0|[1-9]\d*|\d*[A-Za-z-][0-9A-Za-z-]*))*)?(?:\+[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/.test(pkg.version)) {
+      throw new Error(`Invalid KBUI manifest: @kb.ui/${name}`);
+    }
+    return { name, version: pkg.version };
+  }));
+  const version = versions[0]?.version;
+  if (!version || versions.some((pkg) => pkg.version !== version)) {
+    throw new Error(`Mixed KBUI versions: ${versions.map((pkg) => `@kb.ui/${pkg.name}@${pkg.version}`).join(", ")}`);
+  }
+  return version;
+}
+if (process.argv[1] && realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url))) {
+  try {
+    console.log(`KBUI ${await checkVersions(resolve(process.argv[2] ?? process.cwd()))}: synchronized`);
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+}
+export {
+  checkVersions
+};

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

@@ -0,0 +1,15 @@
+import type { ComponentProps } from "react";
+export type BadgeTone = "neutral" | "info" | "success" | "warning" | "danger";
+export type BadgeAppearance = "chip" | "plain";
+/** Static metadata label; use Status for a state that changes. */
+export type BadgeProps = ComponentProps<"span"> & {
+    /** Ink and tint. */
+    tone?: BadgeTone;
+    /** Chip draws a tinted ring; plain is inline text. */
+    appearance?: BadgeAppearance;
+    /** Small uppercase monospace, for identifiers and roles. */
+    mono?: boolean;
+    /** Keep the text's case and spacing, for case-sensitive values such as branches and paths. */
+    preserveCase?: boolean;
+};
+export declare function Badge({ tone, appearance, mono, preserveCase, className, ...props }: BadgeProps): import("react").JSX.Element;

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

@@ -0,0 +1,19 @@
+import { Button as Base } from "@base-ui/react/button";
+export type ButtonVariant = "primary" | "secondary" | "ghost" | "danger";
+export type ButtonSize = "sm" | "md" | "lg" | "icon";
+type ButtonBaseProps = Omit<Base.Props, "className"> & {
+    /** Plain class string; Base UI's function form is not supported. */
+    className?: string;
+    /** Action emphasis: primary main, secondary supporting, ghost quiet, danger destructive. */
+    variant?: ButtonVariant;
+};
+/** Navigation use: pass render={<a href/>} nativeButton={false} role="link". Icon size needs aria-label. */
+export type ButtonProps = ButtonBaseProps & ({
+    /** Height and padding scale; icon is a square for a lone icon. */
+    size?: Exclude<ButtonSize, "icon">;
+} | {
+    size: "icon";
+    "aria-label": string;
+});
+export declare function Button({ variant, size, className, ...props }: ButtonProps): import("react").JSX.Element;
+export {};

package/dist/components/Callout/Callout.d.ts

@@ -0,0 +1,19 @@
+import type { ComponentProps, ReactNode } from "react";
+import { type ClassNames } from "../../utils/kb";
+export type CalloutTone = "neutral" | "info" | "success" | "warning" | "danger";
+/** Inline message with optional actions; text carries the meaning, tone only reinforces it. */
+export type CalloutProps = Omit<ComponentProps<"div">, "title"> & {
+    /** Ink of the edge, tint and icon. */
+    tone?: CalloutTone;
+    /** Short heading line. */
+    title?: ReactNode;
+    /** Caller-provided decorative icon. */
+    icon?: ReactNode;
+    /** Buttons that resolve the message. */
+    actions?: ReactNode;
+    /** Announce changes: adds role="status" and nothing else. */
+    live?: boolean;
+    /** Classes for inner parts, keyed by part. */
+    classNames?: ClassNames<"icon" | "content" | "title" | "body" | "actions">;
+};
+export declare function Callout({ classNames, tone, title, icon, actions, live, className, children, ...props }: CalloutProps): import("react").JSX.Element;

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

@@ -0,0 +1,12 @@
+import { type ComponentProps } from "react";
+type Container = "article" | "div" | "li";
+export type CardProps<T extends Container = "article"> = ComponentProps<T> & {
+    /** Semantic container; links and controls stay caller-owned. */
+    as?: T;
+    /** Outlined surface or unstyled list content. */
+    appearance?: "outlined" | "plain";
+};
+export declare function Card<T extends Container = "article">({ as, appearance, className, ...props }: CardProps<T>): import("react").DetailedReactHTMLElement<Omit<CardProps<T>, "appearance" | "as" | "className"> & {
+    className: string;
+} & Record<`data-${string}`, string>, HTMLElement>;
+export {};

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

@@ -0,0 +1,23 @@
+import { type ComponentProps } from "react";
+import { type ClassNames } from "../../utils/kb";
+export type CheckboxProps = Omit<ComponentProps<"input">, "type" | "checked" | "defaultChecked" | "onChange" | "size"> & {
+    /** Visible accessible label. */
+    label: string;
+    /** Controlled checked state. */
+    checked: boolean;
+    /** Receives next checked state; mixed resolves to checked. */
+    onCheckedChange: (checked: boolean) => void;
+    /** Announce a mixed aggregate selection. */
+    indeterminate?: boolean;
+    /** Hide label text visually. */
+    visuallyHidden?: boolean;
+    /** Helper text associated with the input. */
+    description?: string;
+    /** Visible error; marks the input invalid. */
+    error?: string;
+    /** Class on the native input slot. */
+    controlClassName?: string;
+    /** Classes for inner parts, keyed by part. */
+    classNames?: ClassNames<"control" | "label" | "mark" | "tick" | "mixed" | "description" | "error">;
+};
+export declare function Checkbox({ classNames, label, checked, onCheckedChange, indeterminate, visuallyHidden, description, error, disabled, readOnly, className, controlClassName, id: providedId, ref, style, "aria-invalid": callerAriaInvalid, ...props }: CheckboxProps): import("react").JSX.Element;

package/dist/components/Code/Code.d.ts

@@ -0,0 +1,3 @@
+import type { ComponentProps } from "react";
+export type CodeProps = ComponentProps<"code">;
+export declare function Code({ className, ...props }: CodeProps): import("react").JSX.Element;

package/dist/components/Combobox/Combobox.d.ts

@@ -0,0 +1,65 @@
+import { Combobox as Base } from "@base-ui/react/combobox";
+import { type ComponentPropsWithoutRef, type ReactNode } from "react";
+import { type ClassNames } from "../../utils/kb";
+/** Single selectable option in a Combobox list. */
+export interface ComboboxOption {
+    /** Option value committed to `onValueChange`. */
+    value: string;
+    /** Visible option label used for display and filtering. */
+    label: string;
+    /** Prevent selecting this option while keeping it visible. */
+    disabled?: boolean;
+}
+/** Styleable inner anatomy slots of Combobox. */
+export type ComboboxSlot = "label" | "shell" | "input" | "actions" | "clear" | "trigger" | "positioner" | "popup" | "list" | "option" | "optionIndicator" | "optionLabel" | "empty" | "description" | "error";
+/** Props for the searchable single-select Combobox component. */
+export interface ComboboxProps extends Omit<ComponentPropsWithoutRef<"div">, "defaultValue" | "onChange"> {
+    /** Visible label naming the combobox input. */
+    label: string;
+    /** Selectable options shown and filtered in the popup list. */
+    options: readonly ComboboxOption[];
+    /** Selected option value, or `null` when nothing is selected. */
+    value: string | null;
+    /** Called when the user selects or clears an option. */
+    onValueChange: (value: string | null) => void;
+    /** Placeholder text shown when the input is empty. */
+    placeholder?: string;
+    /** Message announced and shown when no options match the query. */
+    emptyMessage?: ReactNode;
+    /** Control height and typography scale. */
+    size?: "sm" | "md" | "lg";
+    /** Supporting helper text linked through `aria-describedby`. */
+    description?: ReactNode;
+    /** Validation error message; marks the control invalid when truthy. */
+    error?: ReactNode;
+    /** Mark the control invalid without an error message. */
+    invalid?: boolean;
+    /** Disable interaction and form submission. */
+    disabled?: boolean;
+    /** Allow focus and inspection while preventing value changes. */
+    readOnly?: boolean;
+    /** Require a selection for form validation. */
+    required?: boolean;
+    /** Form field name for native form submission. */
+    name?: string;
+    /** Controlled popup open state. */
+    open?: boolean;
+    /** Initial popup open state when uncontrolled. */
+    defaultOpen?: boolean;
+    /** Called when the popup opens or closes. */
+    onOpenChange?: (open: boolean) => void;
+    /** Controlled search query text inside the input. */
+    inputValue?: string;
+    /** Called when the search query text changes. */
+    onInputValueChange?: (inputValue: string) => void;
+    /** Accessible name for the clear button (defaults to `"Clear {label}"`). */
+    clearLabel?: string;
+    /** Accessible name for the popup toggle button (defaults to `"Toggle {label} options"`). */
+    toggleLabel?: string;
+    /** Portal host; defaults to field root to retain nested themes. */
+    container?: Base.Portal.Props["container"];
+    /** Extra classes for inner parts, keyed by slot name. */
+    classNames?: ClassNames<ComboboxSlot>;
+}
+/** Searchable single-choice combobox with type-to-filter and removable selection. */
+export declare const Combobox: import("react").ForwardRefExoticComponent<ComboboxProps & import("react").RefAttributes<HTMLInputElement>>;

package/dist/components/Container/Container.d.ts

@@ -0,0 +1,14 @@
+import type { LayoutElementProps } from "../../utils/layout";
+export type ContainerElement = "div" | "main" | "section" | "article" | "aside" | "header" | "footer";
+export type ContainerSize = "sm" | "md" | "lg" | "full";
+export type ContainerProps<T extends ContainerElement = "div"> = LayoutElementProps<T> & {
+    /** Maximum outer width, including gutters. */
+    size?: ContainerSize;
+    /** Shared responsive gutters; disable when the parent owns padding. */
+    gutter?: boolean;
+};
+export declare function Container<T extends ContainerElement = "div">({ as, size, gutter, className, ...props }: ContainerProps<T>): import("react").DetailedReactHTMLElement<Omit<ContainerProps<T>, "as" | "className" | "gutter" | "size"> & {
+    "data-gutter": undefined;
+} & {
+    className: string;
+} & Record<`data-${string}`, string>, HTMLElement>;

package/dist/components/Dialog/Dialog.d.ts

@@ -0,0 +1,50 @@
+import { Dialog as Base } from "@base-ui/react/dialog";
+import type { ComponentProps, ReactNode } from "react";
+import type { ClassNames } from "../../utils/kb";
+export type DialogProps = Base.Root.Props;
+export type DialogTriggerProps = Base.Trigger.Props;
+export type DialogCloseProps = Base.Close.Props;
+export type DialogTitleProps = Omit<Base.Title.Props, "className"> & {
+    /** Plain class string; Base UI's function form is not supported. */
+    className?: string;
+};
+export type DialogDescriptionProps = Omit<Base.Description.Props, "className"> & {
+    /** Plain class string; Base UI's function form is not supported. */
+    className?: string;
+};
+export type DialogActionsProps = ComponentProps<"div">;
+export type DialogSectionProps = ComponentProps<"div">;
+export type DialogContentProps = Omit<Base.Popup.Props, "className" | "title"> & {
+    /** Accessible name; mutually exclusive with a composed Dialog.Title. */
+    title?: ReactNode;
+    /** Accessible description; mutually exclusive with a composed Dialog.Description. */
+    description?: ReactNode;
+    /** Plain class string; Base UI's function form is not supported. */
+    className?: string;
+    /** Portal target; defaults to document.body. */
+    container?: Base.Portal.Props["container"];
+    /** Classes for inner parts, keyed by part. */
+    classNames?: ClassNames<"backdrop">;
+};
+declare function DialogRoot(props: DialogProps): import("react").JSX.Element;
+declare function DialogTrigger(props: DialogTriggerProps): import("react").JSX.Element;
+declare function DialogClose(props: DialogCloseProps): import("react").JSX.Element;
+declare function DialogTitle({ className, ...props }: DialogTitleProps): import("react").JSX.Element;
+declare function DialogDescription({ className, ...props }: DialogDescriptionProps): import("react").JSX.Element;
+declare function DialogActions({ className, ...props }: DialogActionsProps): import("react").JSX.Element;
+declare function DialogHeader({ className, ...props }: DialogSectionProps): import("react").JSX.Element;
+declare function DialogBody({ className, ...props }: DialogSectionProps): import("react").JSX.Element;
+declare function DialogFooter({ className, ...props }: DialogSectionProps): import("react").JSX.Element;
+declare function DialogContent({ classNames, title, description, container, children, className, ...props }: DialogContentProps): import("react").JSX.Element;
+export declare const Dialog: typeof DialogRoot & {
+    Trigger: typeof DialogTrigger;
+    Content: typeof DialogContent;
+    Title: typeof DialogTitle;
+    Description: typeof DialogDescription;
+    Close: typeof DialogClose;
+    Actions: typeof DialogActions;
+    Header: typeof DialogHeader;
+    Body: typeof DialogBody;
+    Footer: typeof DialogFooter;
+};
+export {};

package/dist/components/ErrorSummary/ErrorSummary.d.ts

@@ -0,0 +1,28 @@
+import { type ComponentProps, type MouseEvent, type ReactNode } from "react";
+import { type ClassNames } from "../../utils/kb";
+export type ErrorSummaryHeadingLevel = 2 | 3 | 4;
+export type ErrorSummaryPart = "title" | "description" | "list" | "item" | "link";
+export interface ErrorSummaryItem {
+    /** Optional key when multiple items point to the same href. */
+    id?: string | undefined;
+    /** Anchor fragment such as "#email" targeting the invalid field or group. */
+    href: string;
+    /** Actionable message naming the field and how to fix it. */
+    label: ReactNode;
+}
+export interface ErrorSummaryProps extends Omit<ComponentProps<"div">, "title"> {
+    /** Summary heading displayed above the error list. */
+    title?: ReactNode | undefined;
+    /** Optional guidance shown between the heading and list. */
+    description?: ReactNode | undefined;
+    /** Ordered field errors with fragment links for focus recovery. */
+    items: readonly ErrorSummaryItem[];
+    /** Document heading rank for the summary title. */
+    headingLevel?: ErrorSummaryHeadingLevel | undefined;
+    /** Callback fired when a recovery link is activated. */
+    onItemSelect?: ((href: string, event: MouseEvent<HTMLAnchorElement>) => void) | undefined;
+    /** Classes for the title, description, list, item and link slots. */
+    classNames?: ClassNames<ErrorSummaryPart> | undefined;
+}
+/** Focusable form-level validation alert that links each error to its field. */
+export declare const ErrorSummary: ({ ref, title, description, items, headingLevel, onItemSelect, tabIndex, className, classNames, "aria-labelledby": ariaLabelledBy, "aria-describedby": ariaDescribedBy, ...props }: ErrorSummaryProps) => import("react").JSX.Element | null;

package/dist/components/Fieldset/Fieldset.d.ts

@@ -0,0 +1,17 @@
+import { type ComponentProps, type ReactNode } from "react";
+import { type ClassNames } from "../../utils/kb";
+export type FieldsetPart = "legend" | "description" | "fields" | "error";
+export interface FieldsetProps extends ComponentProps<"fieldset"> {
+    /** Group heading rendered inside the native legend element. */
+    legend: ReactNode;
+    /** Hide the legend visually while keeping the accessible group name. */
+    visuallyHidden?: boolean | undefined;
+    /** Supporting context explaining the grouped fields. */
+    description?: ReactNode | undefined;
+    /** Group-level validation error message. */
+    error?: ReactNode | undefined;
+    /** Classes for the legend, description, fields and error slots. */
+    classNames?: ClassNames<FieldsetPart> | undefined;
+}
+/** Semantic fieldset and legend section that groups related form controls. */
+export declare const Fieldset: ({ ref, legend, visuallyHidden, description, error, disabled, className, classNames, children, "aria-describedby": ariaDescribedBy, "aria-invalid": callerAriaInvalid, ...props }: FieldsetProps) => import("react").JSX.Element;

package/dist/components/FileInput/FileInput.d.ts

@@ -0,0 +1,59 @@
+import { type ComponentProps, type ReactNode, type Ref } from "react";
+import { type ClassNames } from "../../utils/kb";
+export type FileInputItem = {
+    /** Stable unique identity independent of display name. */
+    id: string;
+    /** Visible filename and default accessible removal name. */
+    name: string;
+    /** Caller-owned metadata such as size or processing status. */
+    description?: ReactNode;
+};
+export type FileInputProps = Omit<ComponentProps<"div">, "onChange" | "children" | "defaultValue"> & {
+    /** Accessible field label. */
+    label: string;
+    /** Retained items; caller owns acceptance and list updates. */
+    items: readonly FileInputItem[];
+    /** Receives original native File objects without policy filtering. */
+    onFiles: (files: File[]) => void;
+    /** Requests removal; focus moves only after items change. */
+    onRemove: (id: string) => void;
+    /** Native picker hint; callers must validate selected files. */
+    accept?: string;
+    /** Allow multiple selections; defaults to true. */
+    multiple?: boolean;
+    /** Block selection, removal and mutation callbacks. */
+    disabled?: boolean;
+    /** Keep retained items readable while blocking changes. */
+    readOnly?: boolean;
+    /** Helper text associated with picker action. */
+    description?: string;
+    /** Caller-owned rejection/error text; announced when shown. */
+    error?: string;
+    /** Hide field label visually while retaining accessible name. */
+    visuallyHidden?: boolean;
+    /** Localized picker action; defaults to Choose files. */
+    chooseLabel?: string;
+    /** Localized empty list message. */
+    emptyMessage?: string;
+    /** Localized accessible remove action for an item. */
+    removeLabel?: (item: FileInputItem) => string;
+    /** Localized announcement after controlled removal succeeds. */
+    removedMessage?: (item: FileInputItem) => string;
+    /** Localized native selection announcement; does not imply acceptance. */
+    selectionMessage?: (count: number) => string;
+    /** Custom item content; retain visible file identity. */
+    renderItem?: (item: FileInputItem) => ReactNode;
+    /** Class on picker action. */
+    triggerClassName?: string;
+    /** Class on retained-item list. */
+    listClassName?: string;
+    /** Class on each retained item. */
+    itemClassName?: string;
+    /** Ref to native hidden file input. */
+    inputRef?: Ref<HTMLInputElement>;
+    /** Ref to accessible picker button. */
+    triggerRef?: Ref<HTMLButtonElement>;
+    /** Classes for inner parts, keyed by part. */
+    classNames?: ClassNames<"label" | "trigger" | "list" | "item" | "native" | "description" | "error" | "content" | "name" | "metadata" | "remove" | "empty">;
+};
+export declare function FileInput({ classNames, label, items, onFiles, onRemove, accept, multiple, disabled, readOnly, description, error, visuallyHidden, chooseLabel, emptyMessage, removeLabel, removedMessage, selectionMessage, renderItem, triggerClassName, listClassName, itemClassName, inputRef, triggerRef, className, onBlurCapture, "aria-describedby": callerDescription, "aria-invalid": callerAriaInvalid, ...props }: FileInputProps): import("react").JSX.Element;

package/dist/components/FormActions/FormActions.d.ts

@@ -0,0 +1,10 @@
+import type { ComponentProps } from "react";
+export type FormActionsAlign = "end" | "start" | "between";
+export interface FormActionsProps extends ComponentProps<"div"> {
+    /** Horizontal alignment for form action buttons. */
+    align?: FormActionsAlign | undefined;
+    /** Add a top border and spacing above the action row. */
+    divider?: boolean | undefined;
+}
+/** Wrapping action footer for form submit, reset and secondary buttons. */
+export declare const FormActions: ({ ref, align, divider, className, children, ...props }: FormActionsProps) => import("react").JSX.Element;

package/dist/components/Grid/Grid.d.ts

@@ -0,0 +1,12 @@
+import { type ComponentProps } from "react";
+type Container = "div" | "ul" | "ol";
+export type GridProps<T extends Container = "div"> = ComponentProps<T> & {
+    /** Native container; list children must be list items. */
+    as?: T;
+    /** Responsive equal columns or a single vertical track. */
+    layout?: "auto" | "stack";
+};
+export declare function Grid<T extends Container = "div">({ as, layout, className, ...props }: GridProps<T>): import("react").ReactElement<Omit<GridProps<T>, "as" | "className" | "layout"> & {
+    className: string;
+} & Record<`data-${string}`, string>, string | import("react").JSXElementConstructor<any>>;
+export {};