@cascivo/react 0.2.0 → 0.2.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import { ErrorBoundary, FocusScope, Portal, RovingOrientation, Signal, SuspenseBoundary } from "@cascivo/core";
-import { AnchorHTMLAttributes, ButtonHTMLAttributes, FormHTMLAttributes, HTMLAttributes, InputHTMLAttributes, LabelHTMLAttributes, LiHTMLAttributes, MouseEvent, ReactElement, ReactNode, SelectHTMLAttributes, TextareaHTMLAttributes } from "react";
+import { AnchorHTMLAttributes, ButtonHTMLAttributes, FormHTMLAttributes, HTMLAttributes, ImgHTMLAttributes, InputHTMLAttributes, LabelHTMLAttributes, LiHTMLAttributes, MouseEvent, ReactElement, ReactNode, RefObject, SelectHTMLAttributes, TextareaHTMLAttributes, TimeHTMLAttributes } from "react";
 
 interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
   variant?: 'primary' | 'secondary' | 'ghost' | 'destructive';
@@ -86,6 +86,8 @@ interface ModalProps {
   children?: ReactNode;
   className?: string;
   size?: 'sm' | 'md' | 'lg';
+  /** Allow dragging the dialog by its header (opt-in; CSS translate, no animation library). */
+  draggable?: boolean;
 }
 declare function Modal({
   open,
@@ -94,7 +96,8 @@ declare function Modal({
   description,
   children,
   className,
-  size
+  size,
+  draggable
 }: ModalProps): import("react").JSX.Element;
 interface SpinnerProps extends HTMLAttributes<HTMLSpanElement> {
   size?: 'sm' | 'md' | 'lg';
@@ -154,6 +157,82 @@ declare function Avatar({
   className,
   ...props
 }: AvatarProps): import("react").JSX.Element;
+interface AvatarGroupLabels {
+  /** Accessible label for the +N overflow chip. */
+  more?: (count: number) => string;
+}
+interface AvatarGroupProps extends HTMLAttributes<HTMLDivElement> {
+  /** Cap the number of visible avatars; the rest collapse into a +N chip. */
+  max?: number;
+  /** Override the total count used for the +N chip (when more exist than rendered). */
+  total?: number;
+  /** Overlap amount. */
+  spacing?: 'sm' | 'md' | 'lg';
+  /** Wrap into a grid instead of an overlapping row. */
+  isGrid?: boolean;
+  labels?: AvatarGroupLabels;
+  /** The <Avatar> children. */
+  children?: ReactNode;
+}
+/** Overlapping stack of avatars with a `max` cap and an i18n-labelled +N overflow chip. */
+declare function AvatarGroup({
+  max,
+  total,
+  spacing,
+  isGrid,
+  labels,
+  className,
+  children,
+  ...rest
+}: AvatarGroupProps): import("react").JSX.Element;
+interface UserProps extends HTMLAttributes<HTMLDivElement> {
+  /** Primary identity label (name). */
+  name: ReactNode;
+  /** Secondary line (email, role, …). */
+  description?: ReactNode;
+  /** Forwarded to the composed <Avatar>. */
+  avatarProps?: AvatarProps;
+  /** Optional trailing action slot (e.g. a menu button). */
+  children?: ReactNode;
+}
+/** Identity composite: an Avatar with a name + optional description and trailing action. */
+declare function User({
+  name,
+  description,
+  avatarProps,
+  className,
+  children,
+  ...rest
+}: UserProps): import("react").JSX.Element;
+interface ImageProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, 'placeholder'> {
+  src?: string;
+  alt?: string;
+  /** Image shown if `src` fails to load. Without it, a neutral fallback box renders. */
+  fallbackSrc?: string;
+  width?: string | number;
+  height?: string | number;
+  radius?: 'none' | 'sm' | 'md' | 'lg' | 'full';
+  /** Hover-zoom the image (reduced-motion-safe). */
+  zoom?: boolean;
+  /** Render a bare <img> with no wrapper, placeholder, or zoom (HeroUI parity). */
+  removeWrapper?: boolean;
+  /** Show a blurred placeholder while loading. */
+  isBlurred?: boolean;
+}
+declare function Image({
+  src,
+  alt,
+  fallbackSrc,
+  width,
+  height,
+  radius,
+  zoom,
+  removeWrapper,
+  isBlurred,
+  className,
+  style,
+  ...rest
+}: ImageProps): import("react").JSX.Element;
 interface TextareaProps extends TextareaHTMLAttributes<HTMLTextAreaElement> {
   label?: string;
   hint?: string;
@@ -418,6 +497,45 @@ declare function Breadcrumb({
   className,
   ariaLabel
 }: BreadcrumbProps): import("react").JSX.Element;
+interface TocItem {
+  /** id of the heading/section this entry links to (without the leading `#`) */
+  id: string;
+  label: string;
+  /** heading level (2 = h2, 3 = h3 …); drives indentation. Defaults to 2. */
+  level?: number;
+}
+interface TocProps {
+  items: TocItem[];
+  /**
+   * Controlled active item id. When set, the component reflects this value and
+   * does not run its own scroll-spy. Leave undefined for built-in scroll-spy.
+   */
+  activeId?: string;
+  onActiveChange?: (id: string) => void;
+  /** Override the built-in nav landmark label. */
+  labels?: {
+    nav?: string;
+  };
+  className?: string;
+}
+declare function Toc({
+  items,
+  activeId,
+  onActiveChange,
+  labels,
+  className
+}: TocProps): import("react").JSX.Element;
+interface UseTocFromRegionOptions {
+  /** CSS selector for the headings to collect. Defaults to `h2, h3, h4`. */
+  selector?: string;
+}
+/**
+ * Opt-in convenience: derive a `TocItem[]` signal from the headings inside a
+ * container. Headings must have an `id`. Feed the result to `<Toc items={…} />`.
+ * The controlled `items` API on `Toc` remains the primary, testable surface;
+ * this helper only builds the list.
+ */
+declare function useTocFromRegion(ref: RefObject<HTMLElement | null>, options?: UseTocFromRegionOptions): Signal<TocItem[]>;
 interface HeaderLink {
   label: string;
   href: string;
@@ -1151,6 +1269,34 @@ declare function ContextMenuItem({
   onSelect,
   disabled
 }: ContextMenuItemProps): import("react").JSX.Element;
+interface ComparisonProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onChange'> {
+  /** The base layer, fully visible underneath. */
+  after: ReactNode;
+  /** The top layer, revealed from the start edge up to `position`. */
+  before: ReactNode;
+  /** Divider position as a percentage 0–100. Controlled when provided. */
+  position?: number;
+  /** Initial divider position for uncontrolled use. Default 50. */
+  defaultPosition?: number;
+  onPositionChange?: (position: number) => void;
+  orientation?: 'horizontal' | 'vertical';
+  /** Percentage the Arrow keys move the divider. Default 5. */
+  keyboardStep?: number;
+  /** Accessible label for the divider slider. */
+  label?: string;
+}
+declare function Comparison({
+  after,
+  before,
+  position,
+  defaultPosition,
+  onPositionChange,
+  orientation,
+  keyboardStep,
+  label,
+  className,
+  ...props
+}: ComparisonProps): import("react").JSX.Element;
 interface HoverCardProps {
   children: ReactNode;
   openDelay?: number;
@@ -1666,6 +1812,61 @@ declare function Prose({
   children,
   ...props
 }: ProseProps): import("react").JSX.Element;
+/**
+ * Minimal QR Code encoder (byte mode, versions 1–40, EC levels L/M/Q/H).
+ *
+ * Vendored as owned source to keep `@cascivo` free of runtime dependencies.
+ * Algorithm and lookup tables adapted from Project Nayuki's "QR Code generator
+ * library" (MIT License, https://www.nayuki.io/page/qr-code-generator-library),
+ * trimmed to byte-mode segments with automatic version and mask selection.
+ */
+type ErrorCorrection = 'L' | 'M' | 'Q' | 'H';
+interface QrCodeProps extends Omit<HTMLAttributes<HTMLDivElement>, 'children'> {
+  /** The text or URL to encode. */
+  value: string;
+  /** Rendered size in pixels (width and height). Default 128. */
+  size?: number;
+  /** Error-correction level. Higher tolerates more damage but holds less data. Default 'M'. */
+  errorCorrection?: ErrorCorrection;
+  /** CSS length rounding the code's corners (applied to the container). */
+  radius?: string;
+  /** Module color. Default `currentColor` so the code inherits text color. */
+  fill?: string;
+  /** Background color behind the modules. Default `transparent`. */
+  background?: string;
+  /** Accessible label. Defaults to the i18n built-in "QR code". */
+  label?: string;
+}
+declare function QrCode({
+  value,
+  size,
+  errorCorrection,
+  radius,
+  fill,
+  background,
+  label,
+  className,
+  style,
+  ...props
+}: QrCodeProps): import("react").JSX.Element | null;
+interface RelativeTimeProps extends Omit<TimeHTMLAttributes<HTMLTimeElement>, 'dateTime'> {
+  /** The instant to describe relative to now. */
+  date: Date | number | string;
+  /** Auto-update as time passes. Default true. */
+  sync?: boolean;
+  /** Override "now" (ms since epoch). Mainly for deterministic tests; disables the interval. */
+  now?: number;
+  /** Passed through to Intl.RelativeTimeFormat (e.g. `{ numeric: 'auto' }`). */
+  format?: Intl.RelativeTimeFormatOptions;
+}
+declare function RelativeTime({
+  date,
+  sync,
+  now: nowProp,
+  format,
+  className,
+  ...props
+}: RelativeTimeProps): import("react").JSX.Element;
 interface LabelProps extends LabelHTMLAttributes<HTMLLabelElement> {
   /** Renders into the child element (Slot composition) instead of a native `<label>`. */
   asChild?: boolean;
@@ -1830,12 +2031,15 @@ interface ScrollAreaProps extends HTMLAttributes<HTMLDivElement> {
   width?: string;
   /** Which axes may scroll. */
   orientation?: 'vertical' | 'horizontal' | 'both';
+  /** Edge affordance: box-shadow (default), a mask-image fade (HeroUI ScrollShadow), or none. */
+  edges?: 'shadow' | 'mask' | 'none';
   children?: ReactNode;
 }
 declare function ScrollArea({
   height,
   width,
   orientation,
+  edges,
   className,
   style,
   children,
@@ -2334,6 +2538,8 @@ interface DrawerProps {
     close?: string;
   };
   className?: string;
+  /** Allow dragging the header toward its edge to dismiss (opt-in; CSS translate, no animation library). */
+  swipeToDismiss?: boolean;
 }
 /**
  * Edge-anchored panel. Unlike Sheet's gesture-driven sheet, Drawer is a plain dialog surface that
@@ -2351,7 +2557,8 @@ declare function Drawer({
   description,
   children,
   labels,
-  className
+  className,
+  swipeToDismiss
 }: DrawerProps): import("react").JSX.Element;
 interface NativeSelectOption {
   value: string;
@@ -2616,4 +2823,4 @@ declare function Swap({
   className,
   ...aria
 }: SwapProps): import("react").JSX.Element;
-export { Accordion, AccordionContent, AccordionItem, AccordionItemProps, AccordionProps, AccordionTrigger, Alert, AlertDialog, AlertDialogLabels, AlertDialogProps, AlertProps, AppShell, AppShellProps, AspectRatio, AspectRatioProps, Avatar, AvatarProps, Badge, BadgeProps, Blockquote, BlockquoteProps, Breadcrumb, BreadcrumbItem, BreadcrumbProps, Button, ButtonGroup, ButtonGroupProps, ButtonProps, Calendar, CalendarLabels, CalendarProps, Card, CardContent, CardContentProps, CardFooter, CardFooterProps, CardHeader, CardHeaderProps, CardProps, CardTitle, CardTitleProps, Carousel, CarouselLabels, CarouselProps, ChatBubble, ChatBubbleProps, ChatBubbleSide, Checkbox, CheckboxCard, CheckboxCardProps, CheckboxProps, Code, type CodeLang, CodeProps, CodeSnippet, CodeSnippetProps, Collapsible, CollapsibleProps, ColorPicker, ColorPickerLabels, ColorPickerProps, Column, Combobox, ComboboxLabels, ComboboxOption, ComboboxProps, CommandGroup, CommandItem, CommandMenu, CommandMenuProps, CommandPage, ContainedList, ContainedListItem, ContainedListItemProps, ContainedListProps, ContextMenu, ContextMenuItem, ContextMenuItemProps, ContextMenuProps, CopyButton, CopyButtonProps, DataList, DataListItem, DataListProps, DataTable, DataTableLabels, DataTableProps, DatePicker, DatePickerLabels, DatePickerProps, DateRange, DateRangePicker, DateRangePickerLabels, DateRangePickerProps, DateRangePreset, Dock, DockItem, DockProps, Drawer, DrawerProps, Dropdown, DropdownItem, DropdownProps, Editable, EditableProps, EmptyState, EmptyStateProps, ErrorBoundary, Field, FieldProps, FileUploader, FileUploaderLabels, FileUploaderProps, Filter, FilterOption, FilterProps, FilterVariant, FocusScope, Form, FormConfig, FormProps, FormStore, Header, HeaderLabels, HeaderLink, HeaderPanel, HeaderPanelLabels, HeaderPanelProps, HeaderProps, Heading, HeadingLevel, HeadingProps, HeadingSize, HoverCard, HoverCardContent, HoverCardContentProps, HoverCardProps, HoverCardTrigger, HoverCardTriggerProps, IconButton, IconButtonProps, Indicator, IndicatorPlacement, IndicatorProps, InlineLoading, InlineLoadingProps, InlineLoadingStatus, Input, InputGroup, InputGroupAddon, type InputGroupAddonProps, type InputGroupProps, InputProps, Item, ItemActions, ItemActionsProps, ItemContent, ItemContentProps, ItemDescription, ItemDescriptionProps, ItemMedia, ItemMediaProps, ItemProps, ItemTitle, ItemTitleProps, Join, JoinOrientation, JoinProps, Kbd, KbdProps, Label, LabelProps, Link, LinkProps, List, ListItem, ListItemProps, ListProps, Menu, MenuButton, MenuButtonItem, MenuButtonProps, MenuItem, MenuItemProps, MenuProps, MenuSeparator, MenuTrigger, MenuTriggerProps, Menubar, MenubarItem, MenubarMenu, MenubarProps, Modal, ModalProps, MultiSelect, MultiSelectLabels, MultiSelectOption, MultiSelectProps, NativeSelect, NativeSelectOption, NativeSelectProps, NavigationMenu, NavigationMenuItem, NavigationMenuProps, Notification, NotificationProps, NotificationVariant, NumberInput, NumberInputProps, OtpInput, OtpInputProps, OverflowMenu, OverflowMenuItem, OverflowMenuProps, Pagination, PaginationLabels, PaginationProps, PasswordInput, PasswordInputLabels, PasswordInputProps, Popover, PopoverContent, PopoverContentProps, PopoverProps, PopoverTrigger, PopoverTriggerProps, Portal, Progress, ProgressBar, ProgressBarProps, ProgressCircle, ProgressCircleProps, ProgressIndicator, ProgressIndicatorProps, ProgressProps, ProgressSize, ProgressStep, ProgressVariant, Prose, ProseProps, RadialProgress, RadialProgressProps, RadialProgressSize, RadialProgressVariant, Radio, RadioCard, RadioCardGroup, RadioCardGroupProps, RadioCardProps, RadioGroup, RadioGroupProps, RadioProps, RatingGroup, RatingGroupLabels, RatingGroupProps, Resizable, ResizableProps, ScrollArea, ScrollAreaProps, Search, SearchProps, SegmentedControl, SegmentedControlOption, SegmentedControlProps, Select, SelectOption, SelectProps, Separator, SeparatorProps, Sheet, SheetProps, ShellHeader, ShellHeaderAction, ShellHeaderBrand, ShellHeaderLabels, ShellHeaderNavItem, ShellHeaderNavLink, ShellHeaderNavMenu, ShellHeaderNavMenuItem, ShellHeaderProps, SideNav, SideNavGroup, SideNavItem, SideNavProps, SideNavSubItem, Skeleton, SkeletonProps, SkipNavLink, SkipNavLinkProps, SkipNavTarget, SkipNavTargetProps, Slider, SliderProps, SortDirection, SortState, Spinner, SpinnerProps, Stack, StackProps, type StandardSchemaV1, Stat, StatProps, Status, StatusProps, Step, StepState, Steps, StepsProps, StructuredList, StructuredListItem, StructuredListProps, SuspenseBoundary, Swap, SwapMode, SwapProps, Switcher, SwitcherEntry, SwitcherLink, SwitcherProps, Tabs, TabsContent, TabsContentProps, TabsList, TabsProps, TabsTrigger, TabsTriggerProps, Tag$1 as Tag, TagProps, TagsInput, TagsInputProps, Text, TextProps, Textarea, TextareaProps, Tile, TileProps, TimePicker, TimePickerProps, Timeline, TimelineItem, TimelineProps, ToastOptions, ToastProvider, ToastVariant, Toggle, ToggleGroup, ToggleGroupItem, ToggleGroupProps, ToggleProps, Toggletip, ToggletipPlacement, ToggletipProps, Tooltip, TooltipProps, TreeNode, TreeView, TreeViewProps, UploaderFile, type UsePopoverOptions, type UsePopoverReturn, VisuallyHidden, VisuallyHiddenProps, createForm, dismissAllToasts, fuzzyScore, treeViewMessages, useForm, usePopover, useToast };
+export { Accordion, AccordionContent, AccordionItem, AccordionItemProps, AccordionProps, AccordionTrigger, Alert, AlertDialog, AlertDialogLabels, AlertDialogProps, AlertProps, AppShell, AppShellProps, AspectRatio, AspectRatioProps, Avatar, AvatarGroup, AvatarGroupLabels, AvatarGroupProps, AvatarProps, Badge, BadgeProps, Blockquote, BlockquoteProps, Breadcrumb, BreadcrumbItem, BreadcrumbProps, Button, ButtonGroup, ButtonGroupProps, ButtonProps, Calendar, CalendarLabels, CalendarProps, Card, CardContent, CardContentProps, CardFooter, CardFooterProps, CardHeader, CardHeaderProps, CardProps, CardTitle, CardTitleProps, Carousel, CarouselLabels, CarouselProps, ChatBubble, ChatBubbleProps, ChatBubbleSide, Checkbox, CheckboxCard, CheckboxCardProps, CheckboxProps, Code, type CodeLang, CodeProps, CodeSnippet, CodeSnippetProps, Collapsible, CollapsibleProps, ColorPicker, ColorPickerLabels, ColorPickerProps, Column, Combobox, ComboboxLabels, ComboboxOption, ComboboxProps, CommandGroup, CommandItem, CommandMenu, CommandMenuProps, CommandPage, Comparison, ComparisonProps, ContainedList, ContainedListItem, ContainedListItemProps, ContainedListProps, ContextMenu, ContextMenuItem, ContextMenuItemProps, ContextMenuProps, CopyButton, CopyButtonProps, DataList, DataListItem, DataListProps, DataTable, DataTableLabels, DataTableProps, DatePicker, DatePickerLabels, DatePickerProps, DateRange, DateRangePicker, DateRangePickerLabels, DateRangePickerProps, DateRangePreset, Dock, DockItem, DockProps, Drawer, DrawerProps, Dropdown, DropdownItem, DropdownProps, Editable, EditableProps, EmptyState, EmptyStateProps, ErrorBoundary, Field, FieldProps, FileUploader, FileUploaderLabels, FileUploaderProps, Filter, FilterOption, FilterProps, FilterVariant, FocusScope, Form, FormConfig, FormProps, FormStore, Header, HeaderLabels, HeaderLink, HeaderPanel, HeaderPanelLabels, HeaderPanelProps, HeaderProps, Heading, HeadingLevel, HeadingProps, HeadingSize, HoverCard, HoverCardContent, HoverCardContentProps, HoverCardProps, HoverCardTrigger, HoverCardTriggerProps, IconButton, IconButtonProps, Image, ImageProps, Indicator, IndicatorPlacement, IndicatorProps, InlineLoading, InlineLoadingProps, InlineLoadingStatus, Input, InputGroup, InputGroupAddon, type InputGroupAddonProps, type InputGroupProps, InputProps, Item, ItemActions, ItemActionsProps, ItemContent, ItemContentProps, ItemDescription, ItemDescriptionProps, ItemMedia, ItemMediaProps, ItemProps, ItemTitle, ItemTitleProps, Join, JoinOrientation, JoinProps, Kbd, KbdProps, Label, LabelProps, Link, LinkProps, List, ListItem, ListItemProps, ListProps, Menu, MenuButton, MenuButtonItem, MenuButtonProps, MenuItem, MenuItemProps, MenuProps, MenuSeparator, MenuTrigger, MenuTriggerProps, Menubar, MenubarItem, MenubarMenu, MenubarProps, Modal, ModalProps, MultiSelect, MultiSelectLabels, MultiSelectOption, MultiSelectProps, NativeSelect, NativeSelectOption, NativeSelectProps, NavigationMenu, NavigationMenuItem, NavigationMenuProps, Notification, NotificationProps, NotificationVariant, NumberInput, NumberInputProps, OtpInput, OtpInputProps, OverflowMenu, OverflowMenuItem, OverflowMenuProps, Pagination, PaginationLabels, PaginationProps, PasswordInput, PasswordInputLabels, PasswordInputProps, Popover, PopoverContent, PopoverContentProps, PopoverProps, PopoverTrigger, PopoverTriggerProps, Portal, Progress, ProgressBar, ProgressBarProps, ProgressCircle, ProgressCircleProps, ProgressIndicator, ProgressIndicatorProps, ProgressProps, ProgressSize, ProgressStep, ProgressVariant, Prose, ProseProps, QrCode, QrCodeProps, RadialProgress, RadialProgressProps, RadialProgressSize, RadialProgressVariant, Radio, RadioCard, RadioCardGroup, RadioCardGroupProps, RadioCardProps, RadioGroup, RadioGroupProps, RadioProps, RatingGroup, RatingGroupLabels, RatingGroupProps, RelativeTime, RelativeTimeProps, Resizable, ResizableProps, ScrollArea, ScrollAreaProps, Search, SearchProps, SegmentedControl, SegmentedControlOption, SegmentedControlProps, Select, SelectOption, SelectProps, Separator, SeparatorProps, Sheet, SheetProps, ShellHeader, ShellHeaderAction, ShellHeaderBrand, ShellHeaderLabels, ShellHeaderNavItem, ShellHeaderNavLink, ShellHeaderNavMenu, ShellHeaderNavMenuItem, ShellHeaderProps, SideNav, SideNavGroup, SideNavItem, SideNavProps, SideNavSubItem, Skeleton, SkeletonProps, SkipNavLink, SkipNavLinkProps, SkipNavTarget, SkipNavTargetProps, Slider, SliderProps, SortDirection, SortState, Spinner, SpinnerProps, Stack, StackProps, type StandardSchemaV1, Stat, StatProps, Status, StatusProps, Step, StepState, Steps, StepsProps, StructuredList, StructuredListItem, StructuredListProps, SuspenseBoundary, Swap, SwapMode, SwapProps, Switcher, SwitcherEntry, SwitcherLink, SwitcherProps, Tabs, TabsContent, TabsContentProps, TabsList, TabsProps, TabsTrigger, TabsTriggerProps, Tag$1 as Tag, TagProps, TagsInput, TagsInputProps, Text, TextProps, Textarea, TextareaProps, Tile, TileProps, TimePicker, TimePickerProps, Timeline, TimelineItem, TimelineProps, ToastOptions, ToastProvider, ToastVariant, Toc, TocItem, TocProps, Toggle, ToggleGroup, ToggleGroupItem, ToggleGroupProps, ToggleProps, Toggletip, ToggletipPlacement, ToggletipProps, Tooltip, TooltipProps, TreeNode, TreeView, TreeViewProps, UploaderFile, type UsePopoverOptions, type UsePopoverReturn, type UseTocFromRegionOptions, User, UserProps, VisuallyHidden, VisuallyHiddenProps, createForm, dismissAllToasts, fuzzyScore, treeViewMessages, useForm, usePopover, useToast, useTocFromRegion };