@scalably/ui 0.2.2 → 0.3.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 import * as react from 'react';
-import { ReactNode } from 'react';
+import react__default, { ReactNode, ImgHTMLAttributes } from 'react';
 import * as class_variance_authority_types from 'class-variance-authority/types';
 import { VariantProps } from 'class-variance-authority';
 import * as react_jsx_runtime from 'react/jsx-runtime';
@@ -1092,6 +1092,98 @@ interface SelectProps extends SelectBaseProps {
  */
 declare const Select: react.ForwardRefExoticComponent<SelectProps & react.RefAttributes<HTMLButtonElement | HTMLSelectElement>>;
 
+declare const skeletonVariants: (props?: ({
+    variant?: "text" | "circle" | "rectangle" | null | undefined;
+    size?: "sm" | "md" | "lg" | null | undefined;
+} & class_variance_authority_types.ClassProp) | undefined) => string;
+type SkeletonVariant = NonNullable<VariantProps<typeof skeletonVariants>["variant"]>;
+type SkeletonSize = NonNullable<VariantProps<typeof skeletonVariants>["size"]>;
+interface SkeletonProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "width" | "height">, VariantProps<typeof skeletonVariants> {
+    /**
+     * Width of the skeleton.
+     * If a number is provided, it will be automatically converted to pixels.
+     * @example width={40} → width="40px"
+     * @example width="100%" → width="100%"
+     */
+    width?: string | number;
+    /**
+     * Height of the skeleton.
+     * If a number is provided, it will be automatically converted to pixels.
+     * @example height={40} → height="40px"
+     * @example height="100%" → height="100%"
+     */
+    height?: string | number;
+    /**
+     * Accessible label for screen readers.
+     * Falls back to a generic "Loading" label if not provided.
+     */
+    "aria-label"?: string;
+}
+/**
+ * Skeleton component for displaying loading placeholders with shimmer animation.
+ *
+ * Features:
+ * - Multiple variants: text, circle, rectangle
+ * - Responsive sizes: sm, md, lg
+ * - Custom dimensions via width/height props
+ * - Shimmer animation with reduced motion support
+ * - Full accessibility support
+ *
+ * @example
+ * ```tsx
+ * // Basic text skeleton
+ * <Skeleton variant="text" size="md" width="100%" />
+ *
+ * // Circle avatar skeleton
+ * <Skeleton variant="circle" width={40} height={40} />
+ *
+ * // Custom rectangle
+ * <Skeleton variant="rectangle" width={200} height={100} />
+ * ```
+ */
+declare const Skeleton: react.ForwardRefExoticComponent<SkeletonProps & react.RefAttributes<HTMLDivElement>>;
+
+interface SkeletonTextProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "children"> {
+    /**
+     * Number of lines to render.
+     * @default 3
+     */
+    lines?: number;
+    /**
+     * Spacing between lines.
+     * If a number is provided, it will be automatically converted to pixels.
+     * @default "0.5rem"
+     * @example gap={8} → gap="8px"
+     * @example gap="1rem" → gap="1rem"
+     */
+    gap?: string | number;
+}
+/**
+ * SkeletonText component for creating multi-line text skeleton placeholders.
+ *
+ * Features:
+ * - Configurable number of lines
+ * - Customizable gap between lines
+ * - Natural paragraph ending (last line is 80% width when multiple lines)
+ * - Composed from Skeleton components
+ *
+ * This component saves you from repeating the "flex-col gap + last line width" pattern
+ * and enforces UI consistency across your application.
+ *
+ * @example
+ * ```tsx
+ * // Default 3-line paragraph skeleton
+ * <SkeletonText />
+ *
+ * // Custom 5-line skeleton with larger gap
+ * <SkeletonText lines={5} gap="1rem" />
+ *
+ * // Compact 2-line skeleton
+ * <SkeletonText lines={2} gap={4} />
+ * ```
+ */
+declare const SkeletonText: react.ForwardRefExoticComponent<SkeletonTextProps & react.RefAttributes<HTMLDivElement>>;
+
 type TabsProps = {
     className?: string;
     value?: string;
@@ -1573,6 +1665,301 @@ interface ViewToggleProps {
  */
 declare const ViewToggle: React.FC<ViewToggleProps>;
 
+/**
+ * Centralized catalog of fallback imagery for avatars and generic image slots.
+ * Consumers can reference these to keep placeholder usage consistent.
+ */
+declare const defaultAssets: {
+    readonly avatars: {
+        readonly group: string;
+        readonly profile: string;
+    };
+    readonly placeholders: {
+        readonly image: string;
+    };
+};
+
+type AvatarPlaceholderCategory = keyof typeof defaultAssets;
+type AvatarPlaceholderVariantMap = {
+    [K in AvatarPlaceholderCategory]: keyof (typeof defaultAssets)[K];
+};
+type AvatarPlaceholderVariant<C extends AvatarPlaceholderCategory = AvatarPlaceholderCategory> = AvatarPlaceholderVariantMap[C];
+interface BaseAvatarPlaceholderProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "alt"> {
+    /**
+     * Accessible text describing the placeholder image.
+     * Falls back to a generated description derived from category and variant.
+     */
+    alt?: string;
+}
+interface AvatarPlaceholderProps<C extends AvatarPlaceholderCategory = AvatarPlaceholderCategory> extends BaseAvatarPlaceholderProps {
+    /**
+     * Asset grouping to load from (`avatars` or `placeholders`).
+     */
+    category: C;
+    /**
+     * Asset key within the selected category (e.g. `group`, `profile`, `image`).
+     */
+    variant: AvatarPlaceholderVariant<C>;
+}
+/**
+ * Thin wrapper around the shared default asset catalog that renders placeholder imagery
+ * (e.g. generic avatars) as a standard `<img>` element with sensible defaults.
+ */
+declare const AvatarPlaceholder: react.ForwardRefExoticComponent<AvatarPlaceholderProps<"avatars" | "placeholders"> & react.RefAttributes<HTMLImageElement>>;
+
+declare const logoAssets: {
+    readonly app: {
+        readonly png: string;
+        readonly svg: string;
+    };
+    readonly campaign: {
+        readonly png: string;
+        readonly svg: string;
+    };
+    readonly membership: {
+        readonly png: string;
+        readonly svg: string;
+    };
+    readonly icon: {
+        readonly png: string;
+        readonly svg: string;
+    };
+    readonly "icon-big": {
+        readonly png: string;
+    };
+};
+
+type LogoVariant = keyof typeof logoAssets;
+type LogoFormat = {
+    [K in LogoVariant]: keyof (typeof logoAssets)[K];
+}[LogoVariant];
+interface LogoProps extends Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "alt"> {
+    /**
+     * Which logo variant to render (derived from logo assets).
+     */
+    variant: LogoVariant;
+    /**
+     * File format to render. Defaults to SVG when available, otherwise PNG.
+     */
+    format?: LogoFormat;
+    /**
+     * Accessible description. Falls back to "Scalably {variant} logo".
+     */
+    alt?: string;
+}
+/**
+ * Branded logo renderer that stays tightly coupled to available assets.
+ */
+declare const Logo: react.ForwardRefExoticComponent<LogoProps & react.RefAttributes<HTMLImageElement>>;
+
+interface LoadingScreenProps extends Omit<react__default.HTMLAttributes<HTMLDivElement>, "children"> {
+    /**
+     * Optional loading message displayed below the logo.
+     */
+    message?: string;
+    /**
+     * Backdrop blur amount. Set to 0 to disable blur.
+     * @default 8
+     */
+    backdropBlur?: number;
+    /**
+     * Backdrop opacity (0-1).
+     * @default 0.8
+     */
+    backdropOpacity?: number;
+    /**
+     * Logo size in pixels. Responsive: smaller on mobile, larger on desktop.
+     * @default { mobile: 64, desktop: 80 }
+     */
+    size?: number | {
+        mobile: number;
+        desktop: number;
+    };
+    /**
+     * Accessible label for screen readers.
+     * Falls back to "Loading" or includes message if provided.
+     */
+    "aria-label"?: string;
+}
+/**
+ * Full-screen loading overlay component with animated Scalably logo.
+ *
+ * Features:
+ * - Full-screen overlay with customizable backdrop
+ * - Animated logo with pulse and rotate combination
+ * - Optional loading message
+ * - Full accessibility support
+ * - Respects reduced motion preferences
+ * - Mobile-first responsive design
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <LoadingScreen />
+ *
+ * // With message
+ * <LoadingScreen message="Loading your data..." />
+ *
+ * // Custom backdrop
+ * <LoadingScreen backdropBlur={12} backdropOpacity={0.9} />
+ *
+ * // Custom size
+ * <LoadingScreen size={{ mobile: 48, desktop: 96 }} />
+ * ```
+ */
+declare const LoadingScreen: react__default.ForwardRefExoticComponent<LoadingScreenProps & react__default.RefAttributes<HTMLDivElement>>;
+
+type ImageSourceMode = "both" | "url-only" | "upload-only";
+interface RichTextEditorProps {
+    /** Controlled HTML value of the editor */
+    value: string;
+    /** Called whenever the content changes (HTML string) */
+    onChange: (html: string) => void;
+    /** Optional label rendered above the editor */
+    label?: string;
+    /** Error message shown below the editor and applied to border */
+    error?: string;
+    /** Helper text shown when there is no error */
+    helperText?: string;
+    /** Placeholder text rendered when editor is empty */
+    placeholder?: string;
+    /** Minimum height of the content area (e.g. "160px") */
+    minHeight?: string;
+    /** When true, renders a reduced toolbar (basic formatting only) */
+    simple?: boolean;
+    /** Disables editing and toolbar interaction */
+    disabled?: boolean;
+    /** Optional test id for querying in tests */
+    "data-testid"?: string;
+    /** Additional className for the outer container */
+    containerClassName?: string;
+    /**
+     * Optional handler for image uploads.
+     *
+     * The editor **always** inserts images by URL. This callback is an
+     * optional helper that lets you plug in your own upload flow:
+     *
+     * - When **not provided**:
+     *   - The image popover only shows a "Source URL" field and "Alt text".
+     *   - Users can paste any public image URL and click "Save" to insert it.
+     *
+     * - When **provided**:
+     *   - The image popover also shows an "Upload file" button.
+     *   - After the user selects a file, this function is called with that File.
+     *   - You upload the file (e.g. S3, Firebase, your API) and return a
+     *     Promise that resolves to the public image URL.
+     *   - The returned URL is written into the "Source URL" field, and the
+     *     user can then confirm insertion with "Save".
+     */
+    onImageUpload?: (file: File) => Promise<string>;
+    /**
+     * Controls how users are allowed to provide image sources.
+     *
+     * The editor always stores images as URLs; this setting only affects the UI:
+     *
+     * - "both" (default):
+     *   - Users can type or paste into the Source URL field.
+     *   - If `onImageUpload` is provided, they can also use the Upload file helper.
+     *
+     * - "url-only":
+     *   - Users can only type/paste a URL.
+     *   - The Upload file helper is hidden even if `onImageUpload` is provided.
+     *
+     * - "upload-only":
+     *   - Users can only upload via `onImageUpload`; the Source URL field is
+     *     rendered read-only to display the resolved URL.
+     *   - If `onImageUpload` is not provided, this mode gracefully behaves like
+     *     "url-only" so the image feature is still usable.
+     */
+    imageSourceMode?: ImageSourceMode;
+}
+/**
+ * RichTextEditor - Controlled rich text editor built on top of Tiptap.
+ *
+ * - Exposes a simple HTML-based value/onChange API.
+ * - Renders a toolbar with common formatting controls.
+ * - Mimics the design system's input styling (label, error, helper text).
+ *
+ * **Viewing Content:**
+ * To display the HTML content created with this editor in read-only mode,
+ * use the `RichTextViewer` component. It ensures content rendered in "view"
+ * mode matches "edit" mode styling exactly.
+ *
+ * @example
+ * ```tsx
+ * import { RichTextEditor, RichTextViewer } from '@scalably/ui';
+ *
+ * function BlogPost({ post }) {
+ *   const [content, setContent] = useState(post.content);
+ *
+ *   return (
+ *     <div>
+ *       <RichTextEditor value={content} onChange={setContent} />
+ *       <RichTextViewer content={content} />
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @see RichTextViewer - Read-only viewer component for displaying rich text content
+ */
+declare const RichTextEditor: {
+    ({ value, onChange, label, error, helperText, placeholder, minHeight, simple, disabled, "data-testid": dataTestId, containerClassName, onImageUpload, imageSourceMode, }: RichTextEditorProps): react_jsx_runtime.JSX.Element;
+    displayName: string;
+};
+
+interface RichTextViewerProps {
+    /**
+     * HTML content string to render (typically from RichTextEditor's value prop).
+     * This content will be rendered as-is, so ensure it's sanitized if it comes
+     * from untrusted sources.
+     */
+    content: string;
+    /**
+     * Additional CSS classes to apply to the container.
+     */
+    className?: string;
+    /**
+     * Optional test id for querying in tests.
+     */
+    "data-testid"?: string;
+}
+/**
+ * RichTextViewer - Read-only component for displaying rich text content.
+ *
+ * This component renders HTML content with the same styling as RichTextEditor,
+ * ensuring a consistent appearance between "edit" and "view" modes.
+ *
+ * **Security Note:** This component uses `dangerouslySetInnerHTML` to render
+ * the provided HTML. If the content comes from untrusted sources (e.g., user
+ * input, external APIs), you should sanitize it first using a library like
+ * DOMPurify:
+ *
+ * ```tsx
+ * import DOMPurify from 'isomorphic-dompurify';
+ *
+ * <RichTextViewer content={DOMPurify.sanitize(userContent)} />
+ * ```
+ *
+ * @example
+ * ```tsx
+ * import { RichTextEditor, RichTextViewer } from '@scalably/ui';
+ *
+ * function BlogPost({ post }) {
+ *   return (
+ *     <div>
+ *       <RichTextEditor value={post.content} onChange={setContent} />
+ *       <RichTextViewer content={post.content} />
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+declare const RichTextViewer: {
+    ({ content, className, "data-testid": dataTestId, }: RichTextViewerProps): react_jsx_runtime.JSX.Element;
+    displayName: string;
+};
+
 interface ScalablyUIProviderProps {
     children: React.ReactNode;
     /**
@@ -2689,4 +3076,4 @@ interface YoutubeIconProps extends React.SVGProps<SVGSVGElement> {
  */
 declare const YoutubeIcon: react.MemoExoticComponent<react.ForwardRefExoticComponent<Omit<YoutubeIconProps, "ref"> & react.RefAttributes<SVGSVGElement>>>;
 
-export { BackToTop, type BackToTopProps, Button, type ButtonProps, type ButtonSize, type ButtonVariant, CalendarIcon, type CalendarIconProps, CaptureIcon, type CaptureIconProps, CheckIcon, type CheckIconProps, Checkbox, CheckboxGroup, type CheckboxGroupOption, type CheckboxGroupProps, type CheckboxProps, CloseIcon, type CloseIconProps, DateInput, type DateInputMode, type DateInputProps, DatePicker, type DatePickerMode, type DatePickerProps, DiscordIcon, type DiscordIconProps, Divider, type DividerProps, type DividerVariant, DropUpIcon, type DropUpIconProps, DropdownIcon, type DropdownIconProps, ErrorIcon, type ErrorIconProps, FacebookIcon, type FacebookIconProps, type FieldErrorLike, FileIcon, type FileIconProps, FileUpload, type FileUploadError, type FileUploadFile, FileUploadIcon, type FileUploadIconProps, type FileUploadIconType, type FileUploadProps, type FileUploadSize, type FileUploadVariant, Form, type FormErrorItem, FormErrorSummary, type FormErrorSummaryProps, FormField, type FormFieldProps, type FormProps, GmailIcon, type GmailIconProps, GridIcon, type GridIconProps, ImageIcon, type ImageIconProps, ImageUploadIcon, type ImageUploadIconProps, IndeterminateIcon, type IndeterminateIconProps, InfoIcon, type InfoIconProps, Input, type InputProps, type InputVariant, InstagramIcon, type InstagramIconProps, KakaoTalkIcon, type KakaoTalkIconProps, LineIcon, type LineIconProps, LinkedInIcon, type LinkedInIconProps, ListIcon, type ListIconProps, MessengerIcon, type MessengerIconProps, MinusIcon, type MinusIconProps, MultipleSelectionButton, type MultipleSelectionButtonProps, MultipleSelectionIcon, type MultipleSelectionIconProps, Pagination, type PaginationProps, PlusIcon, type PlusIconProps, QuantityInput, type QuantityInputProps, Radio, RadioGroup, type RadioGroupOption, type RadioGroupProps, type RadioProps, type RangeValue, RedditIcon, type RedditIconProps, ScalablyUIProvider, type ScalablyUIProviderProps, SearchIcon, type SearchIconProps, SearchInput, type SearchInputProps, type SearchInputVariant, Select, type SelectOption, type SelectProps, type SelectVariant, SettingsIcon, type SettingsIconProps, SignalIcon, type SignalIconProps, SlackIcon, type SlackIconProps, StatusBadge, type StatusBadgeProps, type StatusBadgeSize, type StatusBadgeStatus, type StatusBadgeVariant, SuccessIcon, type SuccessIconProps, Tabs, TabsContent, type TabsContentProps, TabsList, type TabsListProps, type TabsProps, TabsTrigger, type TabsTriggerProps, TelegramIcon, type TelegramIconProps, TickIcon, type TickIconProps, TiktokIcon, type TiktokIconProps, TimePicker, type TimePickerProps, ToFirstIcon, type ToFirstIconProps, ToLastIcon, type ToLastIconProps, ToNextIcon, type ToNextIconProps, ToPreviousIcon, type ToPreviousIconProps, Toast, type ToastAction, ToastContainer, type ToastContainerProps, type ToastPosition, type ToastProps, type ToastStatus, Tooltip, type TooltipAlign, type TooltipProps, type TooltipSide, TwitchIcon, type TwitchIconProps, VideoIcon, type VideoIconProps, VideoUploadIcon, type VideoUploadIconProps, type ViewMode, ViewToggle, type ViewToggleProps, WarnIcon, type WarnIconProps, WhatsAppIcon, type WhatsAppIconProps, XIcon, type XIconProps, YoutubeIcon, type YoutubeIconProps, clampDate, cn, daysGrid, debounce, fieldErrorToProps, formatDateLocalized, monthsForLocale, scopeClass, throttle, toDateKey, weekdaysForLocale, zodErrorsToSummary };
+export { AvatarPlaceholder, type AvatarPlaceholderCategory, type AvatarPlaceholderProps, type AvatarPlaceholderVariant, BackToTop, type BackToTopProps, Button, type ButtonProps, type ButtonSize, type ButtonVariant, CalendarIcon, type CalendarIconProps, CaptureIcon, type CaptureIconProps, CheckIcon, type CheckIconProps, Checkbox, CheckboxGroup, type CheckboxGroupOption, type CheckboxGroupProps, type CheckboxProps, CloseIcon, type CloseIconProps, DateInput, type DateInputMode, type DateInputProps, DatePicker, type DatePickerMode, type DatePickerProps, DiscordIcon, type DiscordIconProps, Divider, type DividerProps, type DividerVariant, DropUpIcon, type DropUpIconProps, DropdownIcon, type DropdownIconProps, ErrorIcon, type ErrorIconProps, FacebookIcon, type FacebookIconProps, type FieldErrorLike, FileIcon, type FileIconProps, FileUpload, type FileUploadError, type FileUploadFile, FileUploadIcon, type FileUploadIconProps, type FileUploadIconType, type FileUploadProps, type FileUploadSize, type FileUploadVariant, Form, type FormErrorItem, FormErrorSummary, type FormErrorSummaryProps, FormField, type FormFieldProps, type FormProps, GmailIcon, type GmailIconProps, GridIcon, type GridIconProps, ImageIcon, type ImageIconProps, type ImageSourceMode, ImageUploadIcon, type ImageUploadIconProps, IndeterminateIcon, type IndeterminateIconProps, InfoIcon, type InfoIconProps, Input, type InputProps, type InputVariant, InstagramIcon, type InstagramIconProps, KakaoTalkIcon, type KakaoTalkIconProps, LineIcon, type LineIconProps, LinkedInIcon, type LinkedInIconProps, ListIcon, type ListIconProps, LoadingScreen, type LoadingScreenProps, Logo, type LogoFormat, type LogoProps, type LogoVariant, MessengerIcon, type MessengerIconProps, MinusIcon, type MinusIconProps, MultipleSelectionButton, type MultipleSelectionButtonProps, MultipleSelectionIcon, type MultipleSelectionIconProps, Pagination, type PaginationProps, PlusIcon, type PlusIconProps, QuantityInput, type QuantityInputProps, Radio, RadioGroup, type RadioGroupOption, type RadioGroupProps, type RadioProps, type RangeValue, RedditIcon, type RedditIconProps, RichTextEditor, type RichTextEditorProps, RichTextViewer, type RichTextViewerProps, ScalablyUIProvider, type ScalablyUIProviderProps, SearchIcon, type SearchIconProps, SearchInput, type SearchInputProps, type SearchInputVariant, Select, type SelectOption, type SelectProps, type SelectVariant, SettingsIcon, type SettingsIconProps, SignalIcon, type SignalIconProps, Skeleton, type SkeletonProps, type SkeletonSize, SkeletonText, type SkeletonTextProps, type SkeletonVariant, SlackIcon, type SlackIconProps, StatusBadge, type StatusBadgeProps, type StatusBadgeSize, type StatusBadgeStatus, type StatusBadgeVariant, SuccessIcon, type SuccessIconProps, Tabs, TabsContent, type TabsContentProps, TabsList, type TabsListProps, type TabsProps, TabsTrigger, type TabsTriggerProps, TelegramIcon, type TelegramIconProps, TickIcon, type TickIconProps, TiktokIcon, type TiktokIconProps, TimePicker, type TimePickerProps, ToFirstIcon, type ToFirstIconProps, ToLastIcon, type ToLastIconProps, ToNextIcon, type ToNextIconProps, ToPreviousIcon, type ToPreviousIconProps, Toast, type ToastAction, ToastContainer, type ToastContainerProps, type ToastPosition, type ToastProps, type ToastStatus, Tooltip, type TooltipAlign, type TooltipProps, type TooltipSide, TwitchIcon, type TwitchIconProps, VideoIcon, type VideoIconProps, VideoUploadIcon, type VideoUploadIconProps, type ViewMode, ViewToggle, type ViewToggleProps, WarnIcon, type WarnIconProps, WhatsAppIcon, type WhatsAppIconProps, XIcon, type XIconProps, YoutubeIcon, type YoutubeIconProps, clampDate, cn, daysGrid, debounce, defaultAssets, fieldErrorToProps, formatDateLocalized, logoAssets, monthsForLocale, scopeClass, throttle, toDateKey, weekdaysForLocale, zodErrorsToSummary };