@mond-design-system/react 1.0.0-alpha.0 → 1.0.0-alpha.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { CSSProperties, HTMLAttributes, JSX, ReactElement, ReactNode, ButtonHTMLAttributes, ElementType, Ref, AnchorHTMLAttributes, InputHTMLAttributes, TextareaHTMLAttributes, SelectHTMLAttributes, LiHTMLAttributes, MouseEventHandler, RefObject, KeyboardEvent } from 'react';
+import { CSSProperties, HTMLAttributes, JSX, ReactElement, ReactNode, ButtonHTMLAttributes, ElementType, Ref, AnchorHTMLAttributes, MouseEventHandler, InputHTMLAttributes, TextareaHTMLAttributes, SelectHTMLAttributes, LiHTMLAttributes, RefObject, KeyboardEvent } from 'react';
 
 /**
  * Join class names, dropping anything falsy.
@@ -234,6 +234,181 @@ interface BadgeProps extends HTMLAttributes<HTMLSpanElement> {
  */
 declare function Badge({ tone, className, ...rest }: BadgeProps): ReactElement;
 
+type ChipVariant = "soft" | "outline";
+interface ChipProps extends HTMLAttributes<HTMLElement> {
+    children: ReactNode;
+    /** Unselected appearance. Default "soft". */
+    variant?: ChipVariant;
+    /** Toggle state. When given on an interactive chip it also sets aria-pressed;
+     * omit for a plain action chip so it does not announce as a toggle. */
+    selected?: boolean;
+    /** Leading glyph, e.g. `<Icon name="check" size="sm" />`. */
+    icon?: ReactNode;
+    /** When provided, Chip renders as a `<button>`. */
+    onClick?: MouseEventHandler;
+    disabled?: boolean;
+}
+/**
+ * Compact pill for filters and single/multi choices. Interactive (a button,
+ * with aria-pressed when `selected` is given) when `onClick` is set, otherwise
+ * a static pill. For a passive content label use Tag instead.
+ *
+ * ```tsx
+ * <Chip selected={filter === "all"} onClick={() => setFilter("all")}>All</Chip>
+ * <Chip variant="outline" icon={<Icon name="pin" size="sm" />}>Nearby</Chip>
+ * ```
+ */
+declare function Chip({ children, variant, selected, icon, onClick, disabled, className, ...rest }: ChipProps): ReactElement;
+
+type ChipGroupGap = "hairline" | "tight" | "base";
+interface ChipGroupProps extends HTMLAttributes<HTMLDivElement> {
+    /** Chips (or any inline items) laid out in a wrapping group. */
+    children: ReactNode;
+    /** Space between items, on the gap scale. Default "tight". */
+    gap?: ChipGroupGap;
+}
+/**
+ * Wrapping row of Chips for multi-select choices inside a form (pick several
+ * days, locations, tags…). Items wrap onto new lines so nothing scrolls
+ * off-screen; use ChipBar for a single-line scrolling filter strip.
+ *
+ * ```tsx
+ * <ChipGroup>
+ *   {days.map((day) => (
+ *     <Chip key={day} selected={picked.has(day)} onClick={() => toggle(day)}>
+ *       {day}
+ *     </Chip>
+ *   ))}
+ * </ChipGroup>
+ * ```
+ */
+declare function ChipGroup({ children, gap, className, ...rest }: ChipGroupProps): ReactElement;
+
+type ChipBarGap = "hairline" | "tight" | "base";
+interface ChipBarProps extends HTMLAttributes<HTMLDivElement> {
+    /** Chips (or any inline items) laid out in a single scrolling row. */
+    children: ReactNode;
+    /** Space between items, on the gap scale. Default "tight". */
+    gap?: ChipBarGap;
+    /** Frame the strip so overflow reads as a scroll area. Default false. */
+    bordered?: boolean;
+    /** Fade the trailing edge to hint that the row scrolls. Default true. */
+    fade?: boolean;
+}
+/**
+ * Horizontally scrollable single-line row of Chips — a filter strip. Items
+ * never wrap; the row scrolls when they overflow. `fade` dissolves the
+ * trailing edge so the last chip hints at more rather than getting chopped
+ * mid-word. Use ChipGroup for a wrapping set of choices inside a form.
+ *
+ * ```tsx
+ * <ChipBar>
+ *   {segments.map((s) => (
+ *     <Chip key={s} selected={s === segment} onClick={() => setSegment(s)}>
+ *       {s}
+ *     </Chip>
+ *   ))}
+ * </ChipBar>
+ * ```
+ */
+declare function ChipBar({ children, gap, bordered, fade, className, ...rest }: ChipBarProps): ReactElement;
+
+type CountButtonTone = "accent" | "danger";
+interface CountButtonProps extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "aria-label" | "aria-pressed"> {
+    /** Glyph shown before the text, e.g. `<Icon name="heart" />` (md). */
+    icon: ReactNode;
+    /** Accessible label (required) — describes the action for screen readers. */
+    label: string;
+    /**
+     * Toggle state. When defined, sets `aria-pressed` and tints the control
+     * with the tone colour. Omit for non-toggle actions (e.g. comment).
+     */
+    active?: boolean;
+    /** Token the active tint reads. Default "accent". */
+    tone?: CountButtonTone;
+    /**
+     * The write behind this action is in flight. Swaps the glyph for a spinner
+     * of the same size and locks the control — a second tap in that window
+     * would toggle the write straight back off.
+     */
+    loading?: boolean;
+    /** Visible text beside the icon — typically a count or a word. */
+    children?: ReactNode;
+}
+/**
+ * Inline, chrome-less pressable pairing an icon with a count or word — like,
+ * comment, react actions. Owns hover, press, disabled, loading and active
+ * (`aria-pressed`) states so consumers never hand-roll button chrome.
+ *
+ * The app owns the glyph, so it also owns the filled/outline swap:
+ *
+ * ```tsx
+ * <CountButton
+ *   icon={<Icon name={liked ? "heart-filled" : "heart"} />}
+ *   label={liked ? "Unlike" : "Like"}
+ *   active={liked}
+ *   loading={likeMutation.isPending}
+ *   onClick={() => likeMutation.mutate()}
+ * >
+ *   {likeCount}
+ * </CountButton>
+ * ```
+ */
+declare function CountButton({ icon, label, active, tone, disabled, loading, className, children, ...rest }: CountButtonProps): ReactElement;
+
+interface DateTimePickerLabels {
+    /** Accessible name of the picker dialog. */
+    dialog: string;
+    previousMonth: string;
+    nextMonth: string;
+    today: string;
+    done: string;
+    hour: string;
+    minute: string;
+    dayPeriod: string;
+}
+interface DateTimePickerProps {
+    /** Current value as an ISO 8601 string. */
+    value?: string | undefined;
+    /** Fires with the combined ISO string when the user confirms. */
+    onChange: (iso: string) => void;
+    /** Shown on the trigger when nothing is selected. */
+    placeholder?: string | undefined;
+    /** Earliest selectable moment as an ISO string. Default: now. */
+    min?: string | undefined;
+    /** Minute granularity. Default 5; use 30 for :00/:30 only. */
+    minuteStep?: number | undefined;
+    disabled?: boolean | undefined;
+    /** Applied to the trigger button so a `<label htmlFor>` can point at it. */
+    id?: string | undefined;
+    /** Field name for the trigger, e.g. "Starts". Announced alongside the value. */
+    "aria-label"?: string | undefined;
+    /** BCP 47 tag for names, week start and hour cycle. Default: runtime locale. */
+    locale?: string | undefined;
+    /** Overrides for the picker's own strings (defaults are English). */
+    labels?: Partial<DateTimePickerLabels> | undefined;
+}
+/**
+ * Mobile-first date + time picker. A trigger styled like Input opens a bottom
+ * sheet with a month calendar (roving-focus grid, arrow keys move the day)
+ * and native Select time controls. Controlled via `value` (ISO); emits the
+ * combined ISO string on confirm. All names, the week start and the 12/24-hour
+ * clock come from `Intl` for the given locale.
+ *
+ * ```tsx
+ * <Field label="Starts">
+ *   <DateTimePicker
+ *     value={startsAt}
+ *     onChange={setStartsAt}
+ *     min={new Date().toISOString()}
+ *     minuteStep={30}
+ *     locale={i18n.language}
+ *   />
+ * </Field>
+ * ```
+ */
+declare function DateTimePicker({ value, onChange, placeholder, min, minuteStep, disabled, id, "aria-label": ariaLabel, locale, labels, }: DateTimePickerProps): ReactElement;
+
 type TagTone = "neutral" | "accent";
 interface TagProps extends HTMLAttributes<HTMLSpanElement> {
     children: ReactNode;
@@ -914,6 +1089,45 @@ interface UseOverlayOptions {
  */
 declare function useOverlay<T extends HTMLElement>(options: UseOverlayOptions): RefObject<T | null>;
 
+interface OverlayHistory {
+    /**
+     * An overlay has opened. The implementation adds a history entry, and calls
+     * `onPop` if the user goes back to it. Returns a dispose for when the
+     * overlay closes some other way — its close button, Escape, the scrim, or
+     * unmounting. The implementation owes the entry back: one left behind is a
+     * back tap that does nothing.
+     */
+    register(onPop: () => void): () => void;
+}
+/**
+ * On a phone, back is also the dismiss gesture: an open overlay that ignores
+ * it costs the user the screen underneath instead. The library owns *when* an
+ * overlay opens and closes; the app owns the history mechanism, because a raw
+ * `history.pushState` from a library corrupts a router's own bookkeeping
+ * (React Router keeps its index in `history.state`).
+ *
+ * Null wherever no app has supplied one — Storybook, a unit test, a consumer
+ * that has not opted in. Overlays go on working; they just do not answer back.
+ *
+ * `useOverlay` registers every open overlay, so Modal, Sheet and
+ * ConfirmDialog are covered with no per-call-site wiring:
+ *
+ * ```tsx
+ * // App root — e.g. backed by the app router:
+ * const overlayHistory = useMemo<OverlayHistory>(() => ({
+ *   register(onPop) {
+ *     pushOverlayEntry(onPop);      // app-owned, via the router
+ *     return () => popOverlayEntry(); // give the entry back
+ *   },
+ * }), []);
+ *
+ * <OverlayHistoryContext.Provider value={overlayHistory}>
+ *   <App />
+ * </OverlayHistoryContext.Provider>
+ * ```
+ */
+declare const OverlayHistoryContext: react.Context<OverlayHistory | null>;
+
 interface Presence {
     /** Keep the element in the DOM (true during exit animation). */
     mounted: boolean;
@@ -939,4 +1153,4 @@ interface RovingGroupOptions {
  */
 declare function useRovingGroup(ref: RefObject<HTMLElement | null>, { selector, orientation }: RovingGroupOptions): (event: KeyboardEvent<HTMLElement>) => void;
 
-export { AppBar, type AppBarProps, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, Badge, type BadgeProps, type BadgeTone, Button, type ButtonProps, type ButtonSize, type ButtonVariant, type CSSVars, Card, CardBody, CardFooter, CardHeader, type CardProps, type CardSectionProps, type CardVariant, Checkbox, type CheckboxProps, ConfirmDialog, type ConfirmDialogProps, Container, type ContainerProps, type ContainerWidth, Divider, type DividerProps, EmptyState, type EmptyStateProps, Field, type FieldContextValue, type FieldProps, Heading, type HeadingLevel, type HeadingProps, type HeadingTone, Icon, type IconProps, IconProvider, type IconProviderProps, type IconRender, type IconRenderProps, type IconSize, Inline, type InlineAlign, type InlineGap, type InlineJustify, type InlineProps, Input, type InputProps, type InputSize, Link, type LinkProps, type LinkVariant, ListGroup, type ListGroupProps, ListItem, type ListItemProps, Modal, ModalBody, ModalFooter, ModalHeader, type ModalProps, PasswordInput, type PasswordInputProps, type Presence, ProgressBar, type ProgressBarProps, Radio, type RadioProps, type RovingGroupOptions, Screen, ScreenContent, SearchField, type SearchFieldProps, type SegmentOption, SegmentedControl, type SegmentedControlProps, Select, type SelectProps, type SelectSize, Sheet, SheetBody, SheetFooter, SheetHeader, type SheetProps, Skeleton, type SkeletonProps, type SkeletonVariant, Spinner, type SpinnerProps, Stack, type StackAlign, type StackGap, type StackProps, Switch, type SwitchProps, Tab, TabBar, TabBarItem, type TabBarItemProps, type TabBarProps, TabList, type TabListProps, TabPanel, type TabPanelProps, type TabProps, Tabs, type TabsProps, Tag, type TagProps, type TagTone, Text, type TextProps, type TextTone, type TextVariant, Textarea, type TextareaProps, type ToastOptions, ToastProvider, type ToastProviderProps, type ToastTone, type UseOverlayOptions, cx, useFieldContext, useOverlay, usePresence, useRovingGroup, useToast };
+export { AppBar, type AppBarProps, Avatar, AvatarGroup, type AvatarGroupProps, type AvatarProps, type AvatarSize, Badge, type BadgeProps, type BadgeTone, Button, type ButtonProps, type ButtonSize, type ButtonVariant, type CSSVars, Card, CardBody, CardFooter, CardHeader, type CardProps, type CardSectionProps, type CardVariant, Checkbox, type CheckboxProps, Chip, ChipBar, type ChipBarGap, type ChipBarProps, ChipGroup, type ChipGroupGap, type ChipGroupProps, type ChipProps, type ChipVariant, ConfirmDialog, type ConfirmDialogProps, Container, type ContainerProps, type ContainerWidth, CountButton, type CountButtonProps, type CountButtonTone, DateTimePicker, type DateTimePickerLabels, type DateTimePickerProps, Divider, type DividerProps, EmptyState, type EmptyStateProps, Field, type FieldContextValue, type FieldProps, Heading, type HeadingLevel, type HeadingProps, type HeadingTone, Icon, type IconProps, IconProvider, type IconProviderProps, type IconRender, type IconRenderProps, type IconSize, Inline, type InlineAlign, type InlineGap, type InlineJustify, type InlineProps, Input, type InputProps, type InputSize, Link, type LinkProps, type LinkVariant, ListGroup, type ListGroupProps, ListItem, type ListItemProps, Modal, ModalBody, ModalFooter, ModalHeader, type ModalProps, type OverlayHistory, OverlayHistoryContext, PasswordInput, type PasswordInputProps, type Presence, ProgressBar, type ProgressBarProps, Radio, type RadioProps, type RovingGroupOptions, Screen, ScreenContent, SearchField, type SearchFieldProps, type SegmentOption, SegmentedControl, type SegmentedControlProps, Select, type SelectProps, type SelectSize, Sheet, SheetBody, SheetFooter, SheetHeader, type SheetProps, Skeleton, type SkeletonProps, type SkeletonVariant, Spinner, type SpinnerProps, Stack, type StackAlign, type StackGap, type StackProps, Switch, type SwitchProps, Tab, TabBar, TabBarItem, type TabBarItemProps, type TabBarProps, TabList, type TabListProps, TabPanel, type TabPanelProps, type TabProps, Tabs, type TabsProps, Tag, type TagProps, type TagTone, Text, type TextProps, type TextTone, type TextVariant, Textarea, type TextareaProps, type ToastOptions, ToastProvider, type ToastProviderProps, type ToastTone, type UseOverlayOptions, cx, useFieldContext, useOverlay, usePresence, useRovingGroup, useToast };