@mucsi96/react-ui 0.4.0 → 0.6.0

package/README.md

@@ -44,6 +44,46 @@ the font to the document root, so applications need no font-family declarations
 or token overrides. No font downloads are needed.
 The optional stylesheet does not import fonts or reset page layouts.
 
+## Application layout
+
+```tsx
+import { AppHeader, AppHeaderActions, AppMain } from '@mucsi96/react-ui';
+
+<AppHeader>
+  <a href="/">My application</a>
+  <AppHeaderActions>
+    <nav aria-label="Main navigation">{/* Application links */}</nav>
+    <ProfileMenu />
+  </AppHeaderActions>
+</AppHeader>
+<AppMain id="main-content">{/* Page content */}</AppMain>
+```
+
+`AppHeader` renders a native `header` with a width-constrained inner flex row.
+Its safe-area top padding sits outside the row's minimum height, so iOS status
+bars do not compress controls. Children wrap as needed. `AppHeaderActions` is a
+wrapping, end-aligned `div`; make any nested navigation groups wrap as well.
+`AppMain` renders a native `main` with matching horizontal gutters, page spacing,
+and bottom safe-area padding. All three accept native element props, including
+`className`, `style`, and React 19 `ref`. They use ordinary document flow.
+
+Set these inherited CSS variables on a common ancestor to customize the layout:
+
+| Variable                 | Default | Purpose                                              |
+| ------------------------ | ------- | ---------------------------------------------------- |
+| `--bt-app-max-width`     | `90rem` | Header row and main maximum width, including gutters |
+| `--bt-app-gutter`        | `1rem`  | Minimum horizontal and bottom page padding           |
+| `--bt-app-header-height` | `4rem`  | Minimum header row height, excluding top safe area   |
+| `--bt-app-header-gap`    | `1rem`  | Space between header children and actions            |
+| `--bt-app-content-gap`   | `3rem`  | Main content top padding                             |
+
+The host document should reset the body margin and include
+`<meta name="viewport" content="width=device-width, initial-scale=1, viewport-fit=cover">`
+for edge-to-edge safe-area handling. The library does not modify document metadata
+or global layout. Keep routing, profile fetching, navigation labels, and menu
+contents in the application; compose profile menus with `MenuTrigger` and
+`Button variant="avatar"`.
+
 ## Buttons
 
 ```tsx
@@ -79,6 +119,12 @@ const options = [{ id: 'apple', label: 'Apple' }, { id: 'pear', label: 'Pear' }]
 <Select label="Fruit" options={options} />
 <ComboBox label="Search fruits" options={options} />
 <Checkbox defaultSelected>Subscribe</Checkbox>
+<NumberField label="Daily limit" name="limit" minValue={1} maxValue={100} step={1} isRequired />
+<CheckboxGroup label="Card types" name="types" isRequired>
+  <Checkbox value="vocabulary">Vocabulary</Checkbox>
+  <Checkbox value="grammar">Grammar</Checkbox>
+</CheckboxGroup>
+<MultiSelect label="Fruits" options={options} />
 <RadioGroup label="Size" defaultValue="medium">
   <Radio value="small">Small</Radio>
   <Radio value="medium">Medium</Radio>
@@ -90,6 +136,22 @@ Labels, descriptions, and validation messages are associated with the input auto
 
 Select options have `{ id, label, isDisabled? }`; React Aria handles selection, typeahead, and filtering. Checkbox and switch controlled state uses `isSelected`/`onChange`; radio group state uses `value`/`onChange`. React Aria form `name` props support native form submissions.
 
+`NumberField` uses numeric `value`/`onChange` or `defaultValue`, with `minValue`,
+`maxValue`, `step`, locale-aware `formatOptions`, and increment/decrement buttons.
+An empty field reports `NaN`; validate before persisting rather than substituting
+zero. React Aria commits and clamps typed values on blur. Use `isRequired` to
+prevent empty native form submission. It supports the same `appearance`,
+`description`, `error`, and `validationBehavior` API as the other fields.
+
+`CheckboxGroup` owns a string-array `value`/`onChange` or `defaultValue`; each
+child `Checkbox` supplies a `value`. Group labels, descriptions, required
+validation, and errors are associated automatically. `name` submits each selected
+value as a separate form entry. `MultiSelect` provides the same compact field as
+`Select` with `selectionMode="multiple"` fixed internally. Use its React Aria
+`value`/`onChange` or `defaultValue` array API for selection; options remain open
+while selecting, and Escape returns focus to the trigger. Disabled options cannot
+be selected. Both controls accept `description`, `error`, and `isRequired`.
+
 ### Field and button sizing
 
 Fields default to `appearance="filled"`, with always-visible floating labels and
@@ -177,6 +239,62 @@ For nested actions, compose `SubmenuTrigger` with a `MenuItem` and another `Menu
 
 Dialog focus is trapped while open and restored to the trigger on close. Escape and outside interaction dismiss by default; `isDismissable={false}` disables outside dismissal, and `isKeyboardDismissDisabled` disables Escape. Use `role="alertdialog"` for important confirmations. Dialogs also support controlled `isOpen`/`onOpenChange` without a `DialogTrigger`. Forms and action layouts are composed as ordinary children. Tooltips accept a single pressable child, `content`, optional `placement`, and `delay`.
 
+Use `size="small" | "medium" | "large"` (24, 32, or 48rem; medium by default)
+to size the outer modal, or `maxWidth` for a CSS width override. All sizes are
+constrained to the viewport with safe-area gutters. The optional `footer` node
+or `({ close }) => ReactNode` keeps actions and the title visible while the body
+scrolls, including in a reduced visual viewport. `className` still styles the
+inner dialog. Keep the form in the body and connect footer submit buttons with
+native `form`/`id` attributes:
+
+```tsx
+<Dialog
+  title="Edit source"
+  size="large"
+  footer={({ close }) => (
+    <>
+      <Button variant="text" onPress={close}>
+        Cancel
+      </Button>
+      <Button type="submit" form="source-form">
+        Save
+      </Button>
+    </>
+  )}
+>
+  <form id="source-form" onSubmit={save}>
+    <TextField label="Source name" isRequired />
+  </form>
+</Dialog>
+```
+
+## Tabs and empty states
+
+```tsx
+<Tabs defaultSelectedKey="items">
+  <TabList aria-label="Collection views">
+    <Tab id="items">Items</Tab>
+    <Tab id="summary">Summary</Tab>
+  </TabList>
+  <TabPanel id="items">
+    <EmptyState
+      title="No items yet"
+      description="Create an item to get started."
+      action={<Button onPress={create}>Add item</Button>}
+    />
+  </TabPanel>
+  <TabPanel id="summary">Summary content</TabPanel>
+</Tabs>
+```
+
+Tabs support controlled `selectedKey`/`onSelectionChange`, disabled tabs,
+`orientation="vertical"`, and React Aria's keyboard activation and focus
+behavior. Match tab and panel IDs. Panels unmount by default; use
+`shouldForceMount` on `TabPanel` to preserve state in an inactive, hidden panel.
+`EmptyState` owns no business behavior: supply the title, description, action,
+and optional children. Its heading defaults to level 2; set `headingLevel` to
+match the surrounding document.
+
 ## Notifications
 
 ```tsx
@@ -247,6 +365,20 @@ This is a semantic HTML table. Columns with `compare` have three-state sorting (
 
 All loading animations respect reduced motion. `Card` supports `outlined` and `elevated`; `Badge` accepts semantic tones and `neutral`. `Heading` supports semantic levels 1–6, `Text` supports `muted`, and `Code` provides inline monospace styling.
 
+Compose stable placeholders with `Skeleton` (`variant="text" | "image" | "row"`,
+optional `width`/`height` CSS values). Each shape is decorative and hidden from
+assistive technology. Wrap a set in `SkeletonGroup label="Loading collection"`
+for one visually hidden status label. Place row placeholders inside table cells,
+not directly inside a `tbody`. Animations stop under reduced motion.
+
+```tsx
+<SkeletonGroup label="Loading collection">
+  <Skeleton variant="image" />
+  <Skeleton width="70%" />
+  <Skeleton variant="row" />
+</SkeletonGroup>
+```
+
 ## Customize with CSS Modules
 
 ```css

package/dist/components/app-layout/app-layout.d.ts

@@ -0,0 +1,7 @@
+import type { ComponentPropsWithRef } from 'react';
+export type AppHeaderProps = ComponentPropsWithRef<'header'>;
+export type AppHeaderActionsProps = ComponentPropsWithRef<'div'>;
+export type AppMainProps = ComponentPropsWithRef<'main'>;
+export declare function AppHeader({ children, className, ...props }: AppHeaderProps): import("react").JSX.Element;
+export declare function AppHeaderActions({ className, ...props }: AppHeaderActionsProps): import("react").JSX.Element;
+export declare function AppMain({ className, ...props }: AppMainProps): import("react").JSX.Element;

package/dist/components/dialog/dialog.d.ts

@@ -1,4 +1,4 @@
-import type { ReactNode } from 'react';
+import type { CSSProperties, ReactNode } from 'react';
 import type { ModalOverlayProps } from 'react-aria-components';
 export { DialogTrigger } from 'react-aria-components';
 export interface DialogProps extends Omit<ModalOverlayProps, 'children' | 'className'> {
@@ -9,5 +9,10 @@ export interface DialogProps extends Omit<ModalOverlayProps, 'children' | 'class
     }) => ReactNode);
     role?: 'dialog' | 'alertdialog';
     className?: string;
+    size?: 'small' | 'medium' | 'large';
+    maxWidth?: CSSProperties['maxWidth'];
+    footer?: ReactNode | ((props: {
+        close: () => void;
+    }) => ReactNode);
 }
-export declare function Dialog({ title, description, children, role, className, isDismissable, ...props }: DialogProps): import("react").JSX.Element;
+export declare function Dialog({ title, description, children, role, className, size, maxWidth, footer, isDismissable, ...props }: DialogProps): import("react").JSX.Element;

package/dist/components/empty-state/empty-state.d.ts

@@ -0,0 +1,9 @@
+import type { ComponentPropsWithRef, ReactNode } from 'react';
+import type { HeadingProps } from '../surface/surface';
+export interface EmptyStateProps extends Omit<ComponentPropsWithRef<'section'>, 'title'> {
+    title: string;
+    description?: ReactNode;
+    action?: ReactNode;
+    headingLevel?: HeadingProps['level'];
+}
+export declare function EmptyState({ title, description, action, headingLevel, children, className, ...props }: EmptyStateProps): import("react").JSX.Element;

package/dist/components/forms/controls.d.ts

@@ -1,10 +1,18 @@
-import type { CheckboxProps as AriaCheckboxProps, RadioGroupProps as AriaRadioGroupProps, RadioProps as AriaRadioProps, SwitchProps as AriaSwitchProps } from 'react-aria-components';
+import type { CheckboxProps as AriaCheckboxProps, CheckboxGroupProps as AriaCheckboxGroupProps, RadioGroupProps as AriaRadioGroupProps, RadioProps as AriaRadioProps, SwitchProps as AriaSwitchProps } from 'react-aria-components';
 import type { ReactNode } from 'react';
 export interface CheckboxProps extends Omit<AriaCheckboxProps, 'children' | 'className'> {
     children: ReactNode;
     className?: string;
 }
 export declare function Checkbox({ children, className, ...props }: CheckboxProps): import("react").JSX.Element;
+export interface CheckboxGroupProps extends Omit<AriaCheckboxGroupProps, 'children' | 'className'> {
+    label: string;
+    children: ReactNode;
+    description?: ReactNode;
+    error?: ReactNode;
+    className?: string;
+}
+export declare function CheckboxGroup({ label, children, description, error, className, ...props }: CheckboxGroupProps): import("react").JSX.Element;
 export interface RadioGroupProps extends Omit<AriaRadioGroupProps, 'children' | 'className'> {
     label: string;
     children: ReactNode;

package/dist/components/forms/number-field.d.ts

@@ -0,0 +1,11 @@
+import type { NumberFieldProps as AriaNumberFieldProps } from 'react-aria-components';
+import type { ReactNode, Ref } from 'react';
+export interface NumberFieldProps extends Omit<AriaNumberFieldProps, 'children' | 'className'> {
+    label: string;
+    description?: ReactNode;
+    error?: ReactNode;
+    appearance?: 'outlined' | 'filled';
+    className?: string;
+    ref?: Ref<HTMLDivElement>;
+}
+export declare function NumberField({ label, description, error, appearance, className, ref, ...props }: NumberFieldProps): import("react").JSX.Element;

package/dist/components/forms/select.d.ts

@@ -14,10 +14,12 @@ interface FieldProps {
     appearance?: 'outlined' | 'filled';
     className?: string;
 }
-export interface SelectProps extends Omit<AriaSelectProps<SelectOption>, keyof FieldProps | 'children' | 'items'>, FieldProps {
+export interface SelectProps<M extends 'single' | 'multiple' = 'single'> extends Omit<AriaSelectProps<SelectOption, M>, keyof FieldProps | 'children' | 'items'>, FieldProps {
 }
-export declare function Select({ label, options, description, error, placeholder, appearance, className, ...props }: SelectProps): import("react").JSX.Element;
+export declare function Select<M extends 'single' | 'multiple' = 'single'>({ label, options, description, error, placeholder, appearance, className, ...props }: SelectProps<M>): import("react").JSX.Element;
 export interface ComboBoxProps extends Omit<AriaComboBoxProps<SelectOption>, keyof FieldProps | 'children' | 'items' | 'defaultItems'>, FieldProps {
 }
+export type MultiSelectProps = Omit<SelectProps<'multiple'>, 'selectionMode' | 'selectedKey' | 'defaultSelectedKey' | 'onSelectionChange'>;
+export declare function MultiSelect(props: MultiSelectProps): import("react").JSX.Element;
 export declare function ComboBox({ label, options, description, error, placeholder, appearance, className, ...props }: ComboBoxProps): import("react").JSX.Element;
 export {};

package/dist/components/skeleton/skeleton.d.ts

@@ -0,0 +1,11 @@
+import type { ComponentPropsWithRef, CSSProperties } from 'react';
+export interface SkeletonProps extends Omit<ComponentPropsWithRef<'div'>, 'children'> {
+    variant?: 'text' | 'image' | 'row';
+    width?: CSSProperties['width'];
+    height?: CSSProperties['height'];
+}
+export declare function Skeleton({ variant, width, height, className, style, ...props }: SkeletonProps): import("react").JSX.Element;
+export interface SkeletonGroupProps extends ComponentPropsWithRef<'div'> {
+    label: string;
+}
+export declare function SkeletonGroup({ label, children, className, ...props }: SkeletonGroupProps): import("react").JSX.Element;

package/dist/components/tabs/tabs.d.ts

@@ -0,0 +1,17 @@
+import type { TabsProps as AriaTabsProps, TabListProps as AriaTabListProps, TabProps as AriaTabProps, TabPanelProps as AriaTabPanelProps } from 'react-aria-components';
+export interface TabsProps extends Omit<AriaTabsProps, 'className'> {
+    className?: string;
+}
+export interface TabListProps<T extends object> extends Omit<AriaTabListProps<T>, 'className'> {
+    className?: string;
+}
+export interface TabProps extends Omit<AriaTabProps, 'className'> {
+    className?: string;
+}
+export interface TabPanelProps extends Omit<AriaTabPanelProps, 'className'> {
+    className?: string;
+}
+export declare function Tabs({ className, ...props }: TabsProps): import("react").JSX.Element;
+export declare function TabList<T extends object>({ className, ...props }: TabListProps<T>): import("react").JSX.Element;
+export declare function Tab({ className, ...props }: TabProps): import("react").JSX.Element;
+export declare function TabPanel({ className, ...props }: TabPanelProps): import("react").JSX.Element;

package/dist/index.d.ts

@@ -1,11 +1,15 @@
+export { AppHeader, AppHeaderActions, AppMain } from './components/app-layout/app-layout';
+export type { AppHeaderProps, AppHeaderActionsProps, AppMainProps, } from './components/app-layout/app-layout';
 export { Button, LinkButton } from './components/button/button';
 export type { ButtonProps, ButtonVariant, LinkButtonProps } from './components/button/button';
 export { TextField } from './components/forms/text-field';
 export type { TextFieldProps } from './components/forms/text-field';
-export { Select, ComboBox } from './components/forms/select';
-export type { SelectProps, ComboBoxProps, SelectOption } from './components/forms/select';
-export { Checkbox, Radio, RadioGroup, Switch } from './components/forms/controls';
-export type { CheckboxProps, RadioProps, RadioGroupProps, SwitchProps, } from './components/forms/controls';
+export { NumberField } from './components/forms/number-field';
+export type { NumberFieldProps } from './components/forms/number-field';
+export { Select, MultiSelect, ComboBox } from './components/forms/select';
+export type { SelectProps, MultiSelectProps, ComboBoxProps, SelectOption, } from './components/forms/select';
+export { Checkbox, CheckboxGroup, Radio, RadioGroup, Switch } from './components/forms/controls';
+export type { CheckboxProps, CheckboxGroupProps, RadioProps, RadioGroupProps, SwitchProps, } from './components/forms/controls';
 export { DonutSlider } from './components/donut-slider/donut-slider';
 export type { DonutSliderProps } from './components/donut-slider/donut-slider';
 export { Menu, MenuItem, MenuPopover, MenuSeparator, MenuTrigger, SubmenuTrigger, } from './components/menu/menu';
@@ -25,3 +29,9 @@ export type { BarLoaderProps, ProgressBarProps } from './components/loader/loade
 export { Card, Badge, Heading, Text, Code, Divider } from './components/surface/surface';
 export type { CardProps, BadgeProps, HeadingProps, TextProps } from './components/surface/surface';
 export type { Tone } from './types';
+export { Tabs, TabList, Tab, TabPanel } from './components/tabs/tabs';
+export type { TabsProps, TabListProps, TabProps, TabPanelProps } from './components/tabs/tabs';
+export { Skeleton, SkeletonGroup } from './components/skeleton/skeleton';
+export type { SkeletonProps, SkeletonGroupProps } from './components/skeleton/skeleton';
+export { EmptyState } from './components/empty-state/empty-state';
+export type { EmptyStateProps } from './components/empty-state/empty-state';