@scalably/ui 0.11.0 → 0.11.2

package/README.md

@@ -7,7 +7,9 @@
 ![TypeScript](https://img.shields.io/badge/TypeScript-5.9.3-blue)
 ![Node](https://img.shields.io/badge/Node-%3E%3D18-green)
 ![React](https://img.shields.io/badge/React-%3E%3D18-blue)
+![Tailwind](https://img.shields.io/badge/Tailwind-3.4-38bdf8?logo=tailwindcss&logoColor=white)
 ![Coverage](https://img.shields.io/badge/coverage-vitest-blue)
+![Maintained](https://img.shields.io/badge/maintained-yes-brightgreen)
 
 A modern, accessible, and fully isolated React component library built with TypeScript and Tailwind CSS. Designed to work seamlessly across multiple projects without style conflicts.
 
@@ -50,9 +52,10 @@ export default function App() {
           <Button className="sui-mt-4" type="submit">Submit</Button>
         </Form>
 
-        {/* Toasts */}
-        <ToastContainer />
-        <Toast status="success" title="Welcome" description="You're all set." />
+        {/* Toasts: render each Toast inside ToastContainer for fixed stacking */}
+        <ToastContainer>
+          <Toast status="success" title="Welcome" message="You're all set." />
+        </ToastContainer>
       </main>
     </ScalablyUIProvider>
   );
@@ -91,7 +94,7 @@ Styles automatically work in portaled components (modals, tooltips, popovers, et
 </Tooltip>
 ```
 
-Note: Toasts in this library are intentionally declarative. Render a `Toast` inside a `ToastContainer` when you want it visible (e.g., based on component state). This avoids hidden globals and keeps UI state predictable. If you prefer an imperative API, you can wrap your own tiny helper around local state to toggle a `Toast` component.
+Note: Toasts are declarative. Put each `Toast` **inside** `ToastContainer` so they stack in a fixed corner of the viewport (`Toast` is not positioned on its own). Toggle visibility with state; use `onClose` after auto-dismiss or when the user dismisses the toast to unmount or dequeue. `ToastContainer` accepts `position` (e.g. `top-right`, `bottom-center`), optional `width`, and `className`. `Toast` uses `message` for body text, `status` of `success` | `info` | `warn` | `error`, plus optional `actions`, `autoCloseMs`, and `showProgress`.
 
 ### 4. React import guidance
 
@@ -152,12 +155,12 @@ import {
   onChange={(date) => console.log(date)}
 />;
 
-// Toast notifications (declarative)
-<ToastContainer>
+// Toast notifications (declarative; nest Toast inside ToastContainer)
+<ToastContainer position="top-right">
   <Toast
     status="success"
     title="Success!"
-    description="Your changes have been saved."
+    message="Your changes have been saved."
   />
 </ToastContainer>;
 
@@ -188,7 +191,7 @@ import {
 This library exposes a set of composable, production-ready primitives. The full list of exports is available in `src/index.ts`, but the main groups are:
 
 - **Form primitives**: `Form`, `FormField`, `FormErrorSummary`, `Input`, `SearchInput`, `QuantityInput`, `CheckBox`, `CheckBoxGroup`, `Radio`, `RadioGroup`, `Select`, `Switch`, `FileUpload`, `DateInput`, `DatePicker`, `TimePicker`
-- **Feedback & status**: `StatusBadge`, `Toast`, `ToastContainer`, `Skeleton`, `SkeletonText`, `Countdown`
+- **Feedback & status**: `StatusBadge`, `Toast`, `ToastContainer` (with `ToastPosition`, stacking at viewport edge), `Skeleton`, `SkeletonText`, `Countdown`
 - **Layout & navigation**: `Tabs`, `TabsList`, `TabsTrigger`, `TabsContent`, `Pagination`, `BackToTop`, `ViewToggle`, `Divider`
 - **Content & rich text**: `RichTextEditor`, `RichTextViewer`, `Tooltip`, `AuthPrompt`, `LoadingScreen`, `WelcomeBackground`
 - **Media & brand**: `AvatarPlaceholder`, `Logo`, `logoAssets`, `defaultAssets`, `welcomeAssets` (all inline React SVGs—no static paths required)

package/dist/index.d.cts

@@ -917,7 +917,9 @@ interface FileUploadError {
 }
 interface FileUploadFile {
     id: string;
-    file: File;
+    file?: File;
+    name?: string;
+    type?: string;
     preview?: string;
     status: "pending" | "uploading" | "success" | "error";
     error?: FileUploadError;
@@ -940,6 +942,11 @@ interface FileUploadProps {
     onUploadSuccess?: (files: File[]) => void;
     onUploadError?: (error: FileUploadError) => void;
     onFileRemove?: (fileId: string) => void;
+    /**
+     * Optional default file source (URL).
+     * This is used to display an existing file when the component initializes.
+     */
+    defaultFileSrc?: string;
     /**
      * Accepted file types. Can be:
      * - MIME types (e.g., 'image/jpeg', 'image/png') - **Recommended**
@@ -2154,54 +2161,86 @@ declare const CelebrationModal: {
     displayName: string;
 };
 
+/**
+ * Semantic variant for a toast: default icon, border, background, and progress color.
+ */
 type ToastStatus = "success" | "info" | "warn" | "error";
+/**
+ * Configuration for one optional action control rendered beside the toast body.
+ */
 interface ToastAction {
+    /** Visible label for the action control. */
     label: string;
+    /** Called when the user activates this action. */
     onClick: () => void;
+    /**
+     * Visual style for the action {@link Button}.
+     * @defaultValue `"link"`
+     */
     variant?: React.ComponentProps<typeof Button>["variant"];
 }
+/** Props for the `Toast` component. */
 interface ToastProps {
+    /** Semantic status; controls default icon and color treatment. */
     status: ToastStatus;
+    /** Primary heading line. */
     title: string;
+    /** Optional supporting text shown under the title. */
     message?: string;
+    /** Additional CSS classes merged onto the toast root element. */
     className?: string;
+    /** Optional actions rendered as buttons; order is preserved. */
     actions?: ToastAction[];
+    /**
+     * Called after the toast has finished dismissing: following the exit animation when
+     * motion is allowed, or immediately when the user prefers reduced motion.
+     * Use this to unmount the toast or remove it from your queue.
+     */
     onClose?: () => void;
+    /**
+     * Auto-dismiss duration in milliseconds. Set to `0` to disable auto-dismiss and the progress UI tied to it.
+     * @defaultValue 5000
+     */
     autoCloseMs?: number;
+    /**
+     * When `autoCloseMs` is greater than zero, shows the default or custom progress indicator.
+     * @defaultValue true
+     */
     showProgress?: boolean;
-    /** Custom icon for this toast (overrides status icon) */
+    /**
+     * Replaces the default status icon when set; ignored if `renderIcon` is provided.
+     */
     customIcon?: React.ReactNode;
-    /** Custom render function for the icon */
+    /**
+     * Full control over icon rendering; takes precedence over `customIcon` and the default status icon.
+     */
     renderIcon?: (status: ToastStatus) => React.ReactNode;
-    /** Custom render function for the close button */
+    /**
+     * Renders the dismiss control; receives `onClick` which must be invoked to start closing.
+     */
     renderCloseButton?: (props: {
         onClick: () => void;
     }) => React.ReactNode;
-    /** Custom render function for the progress bar */
+    /**
+     * Renders the countdown/progress UI; receives remaining percentage (0–100) and status.
+     */
     renderProgress?: (progress: number, status: ToastStatus) => React.ReactNode;
-    /** Hide the close button */
+    /**
+     * When `true`, the default dismiss button is not rendered (you may still use `renderCloseButton`).
+     * @defaultValue false
+     */
     hideCloseButton?: boolean;
 }
 /**
- * Toast - A status notification component with auto-dismiss and action buttons.
+ * Temporary status notification with optional actions, auto-dismiss, and an optional progress indicator.
  *
- * Features:
- * - Multiple status types: success, info, warn, error
- * - Auto-dismiss with configurable timeout
- * - Visual progress bar showing remaining time
- * - Pauses on hover/focus for better UX
- * - Optional action buttons
- * - Manual close button
- * - ARIA live region for screen reader announcements
- * - Smooth animations
- * - Fully customizable icons, close button, and progress bar
+ * @remarks
+ * - Uses `role="status"` (implicit polite live region) for assistive technologies.
+ * - Auto-dismiss pauses while the pointer hovers over the toast or while focus is inside it.
+ * - Enter and exit motion honors `prefers-reduced-motion`; when reduced, dismissal calls `onClose` without waiting for animation.
+ * - For fixed positioning and stacking at a viewport edge, wrap instances in `ToastContainer`.
  *
- * Customization:
- * - `customIcon`: Replace the default status icon
- * - `renderIcon`: Full control over icon rendering
- * - `renderCloseButton`: Custom close button
- * - `renderProgress`: Custom progress bar
- * - `hideCloseButton`: Hide the close button
+ * @see ToastContainer
  *
  * @example
  * ```tsx
@@ -2256,16 +2295,37 @@ interface ToastProps {
  */
 declare const Toast: React.FC<ToastProps>;
 
+/**
+ * Corner or edge alignment for the fixed toast stack relative to the viewport.
+ */
 type ToastPosition = "top-left" | "top-right" | "top-center" | "bottom-left" | "bottom-right" | "bottom-center";
+/**
+ * Props for `ToastContainer`.
+ */
 interface ToastContainerProps {
+    /**
+     * Where the stack is anchored on the screen.
+     * @defaultValue `"top-right"`
+     */
     position?: ToastPosition;
+    /** Additional CSS classes for the outer fixed wrapper. */
     className?: string;
+    /** Toasts or other content; each child is wrapped to restore pointer events. */
     children?: React.ReactNode;
+    /**
+     * Width of the inner column that holds toasts (number is treated as pixels).
+     * @defaultValue `"420px"`
+     */
     width?: number | string;
 }
 /**
- * - Fixed-position portal region to stack toasts at screen edges.
- * - Click-through outer wrapper with pointer-enabled children.
+ * Fixed-position region for stacking one or more `Toast` instances at a viewport edge.
+ *
+ * @remarks
+ * - The outer layer uses `pointer-events: none` so clicks pass through empty space; each child is wrapped with `pointer-events: auto` so toasts and controls remain interactive.
+ * - Sets `role="region"` and `aria-live="polite"` on the outer element for screen reader context when content updates.
+ *
+ * @see Toast
  */
 declare const ToastContainer: React.FC<ToastContainerProps>;
 

package/dist/index.d.ts

@@ -917,7 +917,9 @@ interface FileUploadError {
 }
 interface FileUploadFile {
     id: string;
-    file: File;
+    file?: File;
+    name?: string;
+    type?: string;
     preview?: string;
     status: "pending" | "uploading" | "success" | "error";
     error?: FileUploadError;
@@ -940,6 +942,11 @@ interface FileUploadProps {
     onUploadSuccess?: (files: File[]) => void;
     onUploadError?: (error: FileUploadError) => void;
     onFileRemove?: (fileId: string) => void;
+    /**
+     * Optional default file source (URL).
+     * This is used to display an existing file when the component initializes.
+     */
+    defaultFileSrc?: string;
     /**
      * Accepted file types. Can be:
      * - MIME types (e.g., 'image/jpeg', 'image/png') - **Recommended**
@@ -2154,54 +2161,86 @@ declare const CelebrationModal: {
     displayName: string;
 };
 
+/**
+ * Semantic variant for a toast: default icon, border, background, and progress color.
+ */
 type ToastStatus = "success" | "info" | "warn" | "error";
+/**
+ * Configuration for one optional action control rendered beside the toast body.
+ */
 interface ToastAction {
+    /** Visible label for the action control. */
     label: string;
+    /** Called when the user activates this action. */
     onClick: () => void;
+    /**
+     * Visual style for the action {@link Button}.
+     * @defaultValue `"link"`
+     */
     variant?: React.ComponentProps<typeof Button>["variant"];
 }
+/** Props for the `Toast` component. */
 interface ToastProps {
+    /** Semantic status; controls default icon and color treatment. */
     status: ToastStatus;
+    /** Primary heading line. */
     title: string;
+    /** Optional supporting text shown under the title. */
     message?: string;
+    /** Additional CSS classes merged onto the toast root element. */
     className?: string;
+    /** Optional actions rendered as buttons; order is preserved. */
     actions?: ToastAction[];
+    /**
+     * Called after the toast has finished dismissing: following the exit animation when
+     * motion is allowed, or immediately when the user prefers reduced motion.
+     * Use this to unmount the toast or remove it from your queue.
+     */
     onClose?: () => void;
+    /**
+     * Auto-dismiss duration in milliseconds. Set to `0` to disable auto-dismiss and the progress UI tied to it.
+     * @defaultValue 5000
+     */
     autoCloseMs?: number;
+    /**
+     * When `autoCloseMs` is greater than zero, shows the default or custom progress indicator.
+     * @defaultValue true
+     */
     showProgress?: boolean;
-    /** Custom icon for this toast (overrides status icon) */
+    /**
+     * Replaces the default status icon when set; ignored if `renderIcon` is provided.
+     */
     customIcon?: React.ReactNode;
-    /** Custom render function for the icon */
+    /**
+     * Full control over icon rendering; takes precedence over `customIcon` and the default status icon.
+     */
     renderIcon?: (status: ToastStatus) => React.ReactNode;
-    /** Custom render function for the close button */
+    /**
+     * Renders the dismiss control; receives `onClick` which must be invoked to start closing.
+     */
     renderCloseButton?: (props: {
         onClick: () => void;
     }) => React.ReactNode;
-    /** Custom render function for the progress bar */
+    /**
+     * Renders the countdown/progress UI; receives remaining percentage (0–100) and status.
+     */
     renderProgress?: (progress: number, status: ToastStatus) => React.ReactNode;
-    /** Hide the close button */
+    /**
+     * When `true`, the default dismiss button is not rendered (you may still use `renderCloseButton`).
+     * @defaultValue false
+     */
     hideCloseButton?: boolean;
 }
 /**
- * Toast - A status notification component with auto-dismiss and action buttons.
+ * Temporary status notification with optional actions, auto-dismiss, and an optional progress indicator.
  *
- * Features:
- * - Multiple status types: success, info, warn, error
- * - Auto-dismiss with configurable timeout
- * - Visual progress bar showing remaining time
- * - Pauses on hover/focus for better UX
- * - Optional action buttons
- * - Manual close button
- * - ARIA live region for screen reader announcements
- * - Smooth animations
- * - Fully customizable icons, close button, and progress bar
+ * @remarks
+ * - Uses `role="status"` (implicit polite live region) for assistive technologies.
+ * - Auto-dismiss pauses while the pointer hovers over the toast or while focus is inside it.
+ * - Enter and exit motion honors `prefers-reduced-motion`; when reduced, dismissal calls `onClose` without waiting for animation.
+ * - For fixed positioning and stacking at a viewport edge, wrap instances in `ToastContainer`.
  *
- * Customization:
- * - `customIcon`: Replace the default status icon
- * - `renderIcon`: Full control over icon rendering
- * - `renderCloseButton`: Custom close button
- * - `renderProgress`: Custom progress bar
- * - `hideCloseButton`: Hide the close button
+ * @see ToastContainer
  *
  * @example
  * ```tsx
@@ -2256,16 +2295,37 @@ interface ToastProps {
  */
 declare const Toast: React.FC<ToastProps>;
 
+/**
+ * Corner or edge alignment for the fixed toast stack relative to the viewport.
+ */
 type ToastPosition = "top-left" | "top-right" | "top-center" | "bottom-left" | "bottom-right" | "bottom-center";
+/**
+ * Props for `ToastContainer`.
+ */
 interface ToastContainerProps {
+    /**
+     * Where the stack is anchored on the screen.
+     * @defaultValue `"top-right"`
+     */
     position?: ToastPosition;
+    /** Additional CSS classes for the outer fixed wrapper. */
     className?: string;
+    /** Toasts or other content; each child is wrapped to restore pointer events. */
     children?: React.ReactNode;
+    /**
+     * Width of the inner column that holds toasts (number is treated as pixels).
+     * @defaultValue `"420px"`
+     */
     width?: number | string;
 }
 /**
- * - Fixed-position portal region to stack toasts at screen edges.
- * - Click-through outer wrapper with pointer-enabled children.
+ * Fixed-position region for stacking one or more `Toast` instances at a viewport edge.
+ *
+ * @remarks
+ * - The outer layer uses `pointer-events: none` so clicks pass through empty space; each child is wrapped with `pointer-events: auto` so toasts and controls remain interactive.
+ * - Sets `role="region"` and `aria-live="polite"` on the outer element for screen reader context when content updates.
+ *
+ * @see Toast
  */
 declare const ToastContainer: React.FC<ToastContainerProps>;