react-ui-suite 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 react-ui-suite contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to do so, subject to the
+following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,71 @@
+# react-ui-suite
+
+`react-ui-suite` is a collection of production-ready React components built with Tailwind-friendly class names and ergonomic APIs. The publishable package lives in the `src/` workspace as `react-ui-suite`, while a separate Vite demo app showcases every component with rich previews.
+
+> **ESM-only:** The npm package only publishes ES modules and type declarations under `dist/`. Tools that still require CommonJS entry points must add an extra build step (e.g., `tsup --format cjs`) before consumption.
+
+## Packages
+
+| Folder   | Description                                                                                                               |
+| -------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `.`      | Root workspace published as `@react-ui-suite/root`. It orchestrates tooling/scripts for every workspace but stays private. |
+| `src/`   | Workspace that publishes `react-ui-suite`. `tsup` compiles this folder to `dist/`.                                        |
+| `demos/` | Demo entries that describe each component preview (slug, description, tags, etc.). These files are not published.         |
+| `demo/`  | Standalone Vite gallery that auto-registers every demo entry via `import.meta.glob`. Useful for local development and QA. |
+
+## Installation
+
+```bash
+npm install react-ui-suite
+# or pnpm / yarn
+```
+
+Because the components rely on React, include the peer dependencies in your application:
+
+```
+react@^18
+react-dom@^18
+```
+
+## Usage
+
+```tsx
+import { Badge, Button, Card } from "react-ui-suite";
+
+export function ExampleCard() {
+  return (
+    <Card title="Weekly report">
+      <Badge variant="success">Live</Badge>
+      <p className="mt-3 text-sm text-slate-600">Performance is trending upward for all KPIs.</p>
+      <Button className="mt-4 w-full">View details</Button>
+    </Card>
+  );
+}
+```
+
+Every component (and its related types) is exported from `src/index.ts`, so tree-shaking works out of the box.
+
+## Development
+
+### Build the library workspace
+
+```bash
+npm install          # installs all workspace deps (library + demo)
+npm run build        # builds react-ui-suite via tsup
+npm run test         # executes Vitest for the library (proxied to the src workspace)
+npm run lint         # lints the library source via ESLint (proxied to the src workspace)
+```
+
+`tsup` cleans `src/dist/` automatically and marks `react` / `react-dom` as externals so the published artifacts only contain the suite's code. Linting and tests provide fast feedback before shipping any new component primitives.
+
+### Run the local demo gallery
+
+```bash
+npm run dev          # starts the demo workspace via Vite on http://localhost:5173
+```
+
+The Vite app aliases `react-ui-suite` to `../src`, so you always preview the latest source without publishing. Demo entries live inside `../demos` and are auto-discovered.
+
+## Publishing
+
+`src/package.json` limits the published files to `dist/`, `README.md`, and `LICENSE` so neither the demo app nor the raw source ship to npm. The `prepublishOnly` script automatically runs `build`, `test`, and `lint` so the release payload is always in a healthy state. Once the API begins to stabilize, consider layering in release tooling such as [Changesets](https://github.com/changesets/changesets) or `semantic-release` to track versions/CHANGELOG entries from tagged commits.

package/dist/index.d.ts

@@ -0,0 +1,440 @@
+import * as React from 'react';
+import { ButtonHTMLAttributes, ReactNode } from 'react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+type AlertVariant = "info" | "success" | "warning" | "danger";
+type AlertProps = React.HTMLAttributes<HTMLDivElement> & {
+    title: string;
+    description?: string;
+    variant?: AlertVariant;
+    onDismiss?: () => void;
+};
+declare const Alert: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & {
+    title: string;
+    description?: string;
+    variant?: AlertVariant;
+    onDismiss?: () => void;
+} & React.RefAttributes<HTMLDivElement>>;
+
+type BadgeVariant = "neutral" | "info" | "success" | "warning" | "danger";
+type BadgeProps = React.HTMLAttributes<HTMLSpanElement> & {
+    variant?: BadgeVariant;
+    icon?: React.ReactNode;
+};
+declare const Badge: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLSpanElement> & {
+    variant?: BadgeVariant;
+    icon?: React.ReactNode;
+} & React.RefAttributes<HTMLSpanElement>>;
+
+type ButtonProps = ButtonHTMLAttributes<HTMLButtonElement> & {
+    children: ReactNode;
+};
+declare function Button({ children, onClick, disabled, className, type, style, ...rest }: ButtonProps): react_jsx_runtime.JSX.Element;
+
+type CardProps = Omit<React.HTMLAttributes<HTMLDivElement>, "title"> & {
+    eyebrow?: string;
+    title?: React.ReactNode;
+    actions?: React.ReactNode;
+    footer?: React.ReactNode;
+    muted?: boolean;
+};
+declare const Card: React.ForwardRefExoticComponent<Omit<React.HTMLAttributes<HTMLDivElement>, "title"> & {
+    eyebrow?: string;
+    title?: React.ReactNode;
+    actions?: React.ReactNode;
+    footer?: React.ReactNode;
+    muted?: boolean;
+} & React.RefAttributes<HTMLDivElement>>;
+
+type CheckboxProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" | "onChange" | "checked" | "defaultChecked"> & {
+    label: string;
+    description?: string;
+    checked?: boolean;
+    defaultChecked?: boolean;
+    onChange?: (checked: boolean) => void;
+    indeterminate?: boolean;
+};
+declare const Checkbox: React.ForwardRefExoticComponent<Omit<React.InputHTMLAttributes<HTMLInputElement>, "defaultChecked" | "onChange" | "type" | "checked"> & {
+    label: string;
+    description?: string;
+    checked?: boolean;
+    defaultChecked?: boolean;
+    onChange?: (checked: boolean) => void;
+    indeterminate?: boolean;
+} & React.RefAttributes<HTMLInputElement>>;
+
+type ColorPickerProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" | "value" | "defaultValue" | "onChange"> & {
+    label?: string;
+    value?: string;
+    defaultValue?: string;
+    onChange?: (value: string) => void;
+    swatches?: string[];
+};
+declare const ColorPicker: React.ForwardRefExoticComponent<Omit<React.InputHTMLAttributes<HTMLInputElement>, "defaultValue" | "onChange" | "type" | "value"> & {
+    label?: string;
+    value?: string;
+    defaultValue?: string;
+    onChange?: (value: string) => void;
+    swatches?: string[];
+} & React.RefAttributes<HTMLInputElement>>;
+
+type ComboboxOption<T = unknown> = {
+    id: string;
+    label: string;
+    value?: T;
+    disabled?: boolean;
+};
+type ComboboxRenderState = {
+    active: boolean;
+    selected: boolean;
+};
+type ComboboxProps<T = unknown> = {
+    options: ComboboxOption<T>[];
+    value?: ComboboxOption<T> | null;
+    defaultValue?: ComboboxOption<T> | null;
+    onChange?: (option: ComboboxOption<T> | null) => void;
+    placeholder?: string;
+    disabled?: boolean;
+    className?: string;
+    listClassName?: string;
+    inputClassName?: string;
+    emptyState?: ReactNode;
+    renderOption?: (opt: ComboboxOption<T>, state: ComboboxRenderState) => ReactNode;
+    filter?: (opt: ComboboxOption<T>, query: string) => boolean;
+    openOnFocus?: boolean;
+    ariaLabel?: string;
+};
+
+declare const Combobox: <T>(props: ComboboxProps<T> & React.RefAttributes<HTMLInputElement>) => React.ReactElement | null;
+
+type DatalistInputProps = React.InputHTMLAttributes<HTMLInputElement> & {
+    label?: string;
+    description?: string;
+    options: string[];
+};
+declare const DatalistInput: React.ForwardRefExoticComponent<React.InputHTMLAttributes<HTMLInputElement> & {
+    label?: string;
+    description?: string;
+    options: string[];
+} & React.RefAttributes<HTMLInputElement>>;
+
+type DatePickerProps = {
+    label?: string;
+    description?: string;
+    error?: string;
+    className?: string;
+    disabled?: boolean;
+    value?: string;
+    defaultValue?: string;
+    onChange?: (value: string) => void;
+    type?: "date" | "time";
+    timeIntervalMinutes?: number;
+    use24HourClock?: boolean;
+};
+declare const DatePicker: React.ForwardRefExoticComponent<DatePickerProps & React.RefAttributes<HTMLInputElement>>;
+
+type DialogProps = {
+    open: boolean;
+    onClose: () => void;
+    title: string;
+    description?: string;
+    children: React.ReactNode;
+    footer?: React.ReactNode;
+    modal?: boolean;
+    draggable?: boolean;
+};
+declare function Dialog({ open, onClose, title, description, children, footer, modal, draggable, }: DialogProps): React.ReactPortal | null;
+
+type DisclosureProps = React.DetailsHTMLAttributes<HTMLDetailsElement> & {
+    title: React.ReactNode;
+    subtle?: boolean;
+    defaultOpen?: boolean;
+};
+declare const Disclosure: React.ForwardRefExoticComponent<React.DetailsHTMLAttributes<HTMLDetailsElement> & {
+    title: React.ReactNode;
+    subtle?: boolean;
+    defaultOpen?: boolean;
+} & React.RefAttributes<HTMLDetailsElement>>;
+
+type DropdownProps = {
+    isOpen: boolean;
+    disabled?: boolean;
+    placeholder?: string;
+    displayValue: string;
+    query: string;
+    className?: string;
+    inputClassName?: string;
+    highlightClass?: string;
+    ariaControls?: string;
+    ariaActiveDescendant?: string;
+    ariaLabel?: string;
+    shellClassName?: string;
+    leadingContent?: React.ReactNode;
+    inlineContent?: React.ReactNode;
+    inputProps?: React.InputHTMLAttributes<HTMLInputElement>;
+    inputRef: React.Ref<HTMLInputElement>;
+    chevronRef?: React.Ref<HTMLButtonElement>;
+    showChevron?: boolean;
+    onShellFocusCapture?: (event: React.FocusEvent<HTMLDivElement>) => void;
+    onShellBlurCapture?: (event: React.FocusEvent<HTMLDivElement>) => void;
+    onKeyDownCapture?: (event: React.KeyboardEvent<HTMLDivElement>) => void;
+    onShellMouseDown?: (event: React.MouseEvent<HTMLDivElement>) => void;
+    onInputFocus?: (event: React.FocusEvent<HTMLInputElement>) => void;
+    onInputMouseDown?: (event: React.MouseEvent<HTMLInputElement>) => void;
+    onInputChange?: (event: React.ChangeEvent<HTMLInputElement>) => void;
+    onChevronClick?: () => void;
+    children?: React.ReactNode;
+};
+declare const Dropdown: React.ForwardRefExoticComponent<DropdownProps & React.RefAttributes<HTMLDivElement>>;
+
+type InputFieldProps = React.InputHTMLAttributes<HTMLInputElement> & {
+    label?: string;
+    description?: string;
+    error?: string;
+    leadingIcon?: React.ReactNode;
+    trailingLabel?: string;
+};
+declare const InputField: React.ForwardRefExoticComponent<React.InputHTMLAttributes<HTMLInputElement> & {
+    label?: string;
+    description?: string;
+    error?: string;
+    leadingIcon?: React.ReactNode;
+    trailingLabel?: string;
+} & React.RefAttributes<HTMLInputElement>>;
+
+type NumberInputProps = {
+    label?: string;
+    description?: string;
+    error?: string;
+    className?: string;
+    disabled?: boolean;
+    value?: number;
+    defaultValue?: number;
+    onChange?: (value: number) => void;
+    step?: number;
+    suffix?: React.ReactNode;
+    min?: number;
+    max?: number;
+};
+declare const NumberInput: React.ForwardRefExoticComponent<NumberInputProps & React.RefAttributes<HTMLInputElement>>;
+
+type OutputChipProps = React.OutputHTMLAttributes<HTMLOutputElement> & {
+    tone?: "neutral" | "success" | "warning" | "danger";
+    label?: string;
+};
+declare const OutputChip: React.ForwardRefExoticComponent<React.OutputHTMLAttributes<HTMLOutputElement> & {
+    tone?: "neutral" | "success" | "warning" | "danger";
+    label?: string;
+} & React.RefAttributes<HTMLOutputElement>>;
+
+type PopoverProps = {
+    className?: string;
+    children: (props: {
+        scrollRef: React.MutableRefObject<HTMLUListElement | null>;
+    }) => React.ReactNode;
+};
+declare function Popover({ className, children }: PopoverProps): react_jsx_runtime.JSX.Element;
+
+type CommonProps = {
+    label?: string;
+    description?: string;
+    className?: string;
+};
+type ProgressProps = CommonProps & {
+    value: number;
+    max?: number;
+    showValue?: boolean;
+};
+declare function Progress({ label, description, value, max, showValue, className, }: ProgressProps): react_jsx_runtime.JSX.Element;
+type MeterProps = CommonProps & {
+    value: number;
+    min?: number;
+    max?: number;
+    thresholds?: {
+        value: number;
+        color: string;
+    }[];
+};
+declare function Meter({ label, description, value, min, max, thresholds, className, }: MeterProps): react_jsx_runtime.JSX.Element;
+
+type RadioProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" | "onChange" | "checked" | "defaultChecked"> & {
+    label: string;
+    description?: string;
+    extra?: React.ReactNode;
+    checked?: boolean;
+    defaultChecked?: boolean;
+    onChange?: (checked: boolean) => void;
+};
+declare const Radio: React.ForwardRefExoticComponent<Omit<React.InputHTMLAttributes<HTMLInputElement>, "defaultChecked" | "onChange" | "type" | "checked"> & {
+    label: string;
+    description?: string;
+    extra?: React.ReactNode;
+    checked?: boolean;
+    defaultChecked?: boolean;
+    onChange?: (checked: boolean) => void;
+} & React.RefAttributes<HTMLInputElement>>;
+
+type SelectOption = {
+    label: string;
+    value: string;
+    description?: string;
+    disabled?: boolean;
+};
+type SelectProps = {
+    label?: string;
+    description?: string;
+    error?: string;
+    options: SelectOption[];
+    value?: string;
+    defaultValue?: string;
+    onChange?: (value: string | null) => void;
+    placeholder?: string;
+    className?: string;
+    disabled?: boolean;
+    leadingContent?: React.ReactNode;
+    inlineContent?: React.ReactNode;
+};
+declare function Select({ label, description, error, options, value, defaultValue, onChange, placeholder, className, disabled, leadingContent, inlineContent, }: SelectProps): react_jsx_runtime.JSX.Element;
+
+type SliderRenderProps = {
+    value: number;
+    min: number;
+    max: number;
+    percentage: number;
+    disabled?: boolean;
+    focused: boolean;
+    orientation: "horizontal" | "vertical";
+    reversed: boolean;
+    position: number;
+    trackLength: number;
+    thumbSize: number;
+    trackOffset: number;
+    trackCrossOffset: number;
+    trackThickness: number;
+};
+type SliderProps = Omit<React.InputHTMLAttributes<HTMLInputElement>, "type" | "value" | "defaultValue" | "onChange" | "min" | "max" | "step"> & {
+    label?: string;
+    value?: number;
+    defaultValue?: number;
+    onChange?: (value: number) => void;
+    formatValue?: (value: number) => string;
+    renderTrack?: (props: SliderRenderProps & {
+        children: React.ReactNode;
+    }) => React.ReactNode;
+    renderThumb?: (props: SliderRenderProps) => React.ReactNode;
+    trackClassName?: string;
+    thumbClassName?: string;
+    orientation?: "horizontal" | "vertical";
+    reversed?: boolean;
+    min?: number;
+    max?: number;
+    step?: number;
+    /**
+     * Approximate thumb size along the track axis (used for bounds and progress).
+     * For custom thumbs wider than tall (e.g., pills with labels), set this to the thumb's total width (horizontal) or height (vertical).
+     */
+    thumbSize?: number;
+    /**
+     * Allow the thumb center to travel slightly beyond the track ends. Useful for wide custom thumbs that should visually meet the track edges.
+     */
+    edgeOverlap?: number;
+    /**
+     * How the fill gradient should behave.
+     * - "stretch" (default): gradient is scaled to the filled portion.
+     * - "mask": gradient spans the full track and is revealed up to the thumb.
+     */
+    fillMode?: "stretch" | "mask";
+};
+declare const Slider: React.ForwardRefExoticComponent<Omit<React.InputHTMLAttributes<HTMLInputElement>, "defaultValue" | "onChange" | "type" | "value" | "step" | "max" | "min"> & {
+    label?: string;
+    value?: number;
+    defaultValue?: number;
+    onChange?: (value: number) => void;
+    formatValue?: (value: number) => string;
+    renderTrack?: (props: SliderRenderProps & {
+        children: React.ReactNode;
+    }) => React.ReactNode;
+    renderThumb?: (props: SliderRenderProps) => React.ReactNode;
+    trackClassName?: string;
+    thumbClassName?: string;
+    orientation?: "horizontal" | "vertical";
+    reversed?: boolean;
+    min?: number;
+    max?: number;
+    step?: number;
+    /**
+     * Approximate thumb size along the track axis (used for bounds and progress).
+     * For custom thumbs wider than tall (e.g., pills with labels), set this to the thumb's total width (horizontal) or height (vertical).
+     */
+    thumbSize?: number;
+    /**
+     * Allow the thumb center to travel slightly beyond the track ends. Useful for wide custom thumbs that should visually meet the track edges.
+     */
+    edgeOverlap?: number;
+    /**
+     * How the fill gradient should behave.
+     * - "stretch" (default): gradient is scaled to the filled portion.
+     * - "mask": gradient spans the full track and is revealed up to the thumb.
+     */
+    fillMode?: "stretch" | "mask";
+} & React.RefAttributes<HTMLInputElement>>;
+
+type StackedListItem = {
+    id: string;
+    title: string;
+    description?: string;
+    meta?: string;
+    icon?: React.ReactNode;
+    action?: React.ReactNode;
+};
+type StackedListProps = React.HTMLAttributes<HTMLDivElement> & {
+    items: StackedListItem[];
+    dense?: boolean;
+};
+declare function StackedList({ items, dense, className, ...rest }: StackedListProps): react_jsx_runtime.JSX.Element;
+
+type TableColumn<T> = {
+    key: keyof T;
+    header: string;
+    render?: (value: T[keyof T], row: T) => React.ReactNode;
+    align?: "left" | "right" | "center";
+};
+type TableProps<T> = {
+    columns: TableColumn<T>[];
+    data: T[];
+    caption?: string;
+    className?: string;
+    scrollAreaStyle?: React.CSSProperties;
+    style?: React.CSSProperties;
+};
+declare function Table<T extends Record<string, unknown>>({ columns, data, caption, className, scrollAreaStyle, style, }: TableProps<T>): react_jsx_runtime.JSX.Element;
+
+type TextareaProps = React.TextareaHTMLAttributes<HTMLTextAreaElement> & {
+    label?: string;
+    description?: string;
+    error?: string;
+    maxLength?: number;
+    showCount?: boolean;
+    resizeDirection?: "vertical" | "horizontal" | "both" | "none";
+};
+declare const Textarea: React.ForwardRefExoticComponent<React.TextareaHTMLAttributes<HTMLTextAreaElement> & {
+    label?: string;
+    description?: string;
+    error?: string;
+    maxLength?: number;
+    showCount?: boolean;
+    resizeDirection?: "vertical" | "horizontal" | "both" | "none";
+} & React.RefAttributes<HTMLTextAreaElement>>;
+
+type ToggleProps = Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onChange" | "type"> & {
+    checked?: boolean;
+    defaultChecked?: boolean;
+    onChange?: (checked: boolean) => void;
+};
+declare const Toggle: React.ForwardRefExoticComponent<Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, "onChange" | "type"> & {
+    checked?: boolean;
+    defaultChecked?: boolean;
+    onChange?: (checked: boolean) => void;
+} & React.RefAttributes<HTMLButtonElement>>;
+
+export { Alert, type AlertProps, type AlertVariant, Badge, type BadgeProps, type BadgeVariant, Button, type ButtonProps, Card, type CardProps, Checkbox, type CheckboxProps, ColorPicker, type ColorPickerProps, Combobox, type ComboboxOption, type ComboboxProps, type ComboboxRenderState, DatalistInput, type DatalistInputProps, DatePicker, type DatePickerProps, Dialog, type DialogProps, Disclosure, type DisclosureProps, Dropdown, type DropdownProps, InputField, type InputFieldProps, Meter, type MeterProps, NumberInput, type NumberInputProps, OutputChip, type OutputChipProps, Popover, type PopoverProps, Progress, type ProgressProps, Radio, type RadioProps, Select, type SelectOption, type SelectProps, Slider, type SliderProps, StackedList, type StackedListItem, type StackedListProps, Table, type TableColumn, type TableProps, Textarea, type TextareaProps, Toggle, type ToggleProps };