@ramme-io/ui 1.1.5 → 1.2.0

package/dist/src/blocks/ai/Loader.d.ts

@@ -1,11 +1,29 @@
 import { default as React } from 'react';
 
+export interface LoaderProps {
+    /** The visual style of the loader. */
+    variant?: 'bubble' | 'sparkle' | 'bar';
+    /** Optional text to display next to the animation (e.g., "Thinking...") */
+    label?: string;
+    className?: string;
+}
 /**
  * @wizard
  * @name Loader
- * @description A visual indicator used within an AI Message to show that a response is being generated.
- * @tags ui, ai, feedback, loading
+ * @description A compact, theme-aware animation for indicating AI processing states. Optimized for chat interfaces.
+ * @tags ui, ai, feedback, loading, chat
+ * @props
+ * - name: variant
+ * type: "'bubble' | 'sparkle' | 'bar'"
+ * description: The visual style. 'bubble' is standard for chat. 'sparkle' is for creative generation.
+ * default: 'bubble'
+ * - name: label
+ * type: string
+ * description: Optional text displayed next to the animation.
+ * - name: className
+ * type: string
+ * description: Custom classes for the container.
  * @category ai
  * @id loader
  */
-export declare const Loader: React.FC;
+export declare const Loader: React.FC<LoaderProps>;

package/dist/src/components/forms/DatePicker.d.ts

@@ -2,52 +2,23 @@ import { default as React } from 'react';
 
 export interface DatePickerProps {
     label?: string;
-    onChange: (date: Date | null) => void;
     selected: Date | null;
+    onChange: (date: Date | null) => void;
     className?: string;
     placeholderText?: string;
     dateFormat?: string;
-    isClearable?: boolean;
     minDate?: Date;
     maxDate?: Date;
+    error?: boolean;
+    helperText?: string;
     showTimeSelect?: boolean;
+    isClearable?: boolean;
 }
 /**
  * @wizard
  * @name DatePicker
- * @description A calendar-based input component for selecting single dates, with theme integration.
+ * @description A theme-aware calendar input for selecting dates. Wraps react-datepicker to ensure consistent styling and "Zero Jank" layout stability.
  * @tags form, input, date, calendar, ui
- * @props
- * - name: label
- * type: string
- * description: An optional label displayed above the date picker input field.
- * - name: selected
- * type: Date | null
- * description: The currently selected date object, or `null` if no date is selected.
- * - name: onChange
- * type: (date: Date | null) => void
- * description: Callback function triggered when a new date is selected.
- * - name: className
- * type: string
- * description: Optional additional CSS classes for the date picker's wrapper container.
- * - name: dateFormat
- * type: string
- * description: The format string for displaying the date (e.g., 'MM/dd/yyyy', 'yyyy-MM-dd').
- * - name: showTimeSelect
- * type: boolean
- * description: If true, also allows time selection in addition to date selection.
- * - name: isClearable
- * type: boolean
- * description: If true, displays a clear button to deselect the date.
- * - name: placeholderText
- * type: string
- * description: Text displayed when no date is selected.
- * - name: minDate
- * type: Date
- * description: The earliest selectable date.
- * - name: maxDate
- * type: Date
- * description: The latest selectable date.
  * @category form
  * @id date-picker
  */

package/dist/src/components/forms/FileUpload.d.ts

@@ -6,29 +6,13 @@ interface FileUploadProps {
     acceptedFileTypes?: string;
     label?: string;
     className?: string;
+    helperText?: string;
 }
 /**
  * @wizard
  * @name FileUpload
- * @description A component allowing users to upload files via drag-and-drop or a file browser, with support for multiple files and accepted types.
+ * @description A modern drag-and-drop file upload area with visual feedback and file listing.
  * @tags form, input, upload, files, ui
- * @props
- * - name: onFileUpload
- * type: (files: File[]) => void
- * description: Callback function triggered when files are selected or dropped, providing an array of File objects.
- * - name: multiple
- * type: boolean
- * description: If true, allows the user to select and upload multiple files.
- * default: false
- * - name: acceptedFileTypes
- * type: string
- * description: A string specifying acceptable file types (e.g., ".pdf,.txt,.xml", "image/*").
- * - name: label
- * type: string
- * description: An optional label displayed above the file upload area.
- * - name: className
- * type: string
- * description: Optional additional CSS classes for custom styling of the file upload container.
  * @category form
  * @id file-upload
  */

package/dist/src/components/forms/FormTemplate.d.ts

@@ -1,5 +1,7 @@
 import { default as React } from 'react';
+import { SelectOption } from '../forms/Select';
 import { MultiSelectOption } from '../forms/MultiSelect';
+import { SegmentedControlOption } from '../forms/SegmentedControl';
 
 interface FormFieldBase {
     name: string;
@@ -7,6 +9,8 @@ interface FormFieldBase {
     className?: string;
     disabled?: boolean;
     colSpan?: number;
+    helperText?: string;
+    required?: boolean;
 }
 interface FormInput extends FormFieldBase {
     type: 'text' | 'email' | 'password' | 'number';
@@ -19,10 +23,6 @@ interface FormTextarea extends FormFieldBase {
     value?: string;
     rows?: number;
 }
-interface SelectOption {
-    value: string | number;
-    label: string;
-}
 interface FormSelect extends FormFieldBase {
     type: 'select';
     options: SelectOption[];
@@ -52,13 +52,24 @@ interface FormMultiSelect extends FormFieldBase {
     type: 'multiselect';
     options: MultiSelectOption[];
     value?: MultiSelectOption[] | null;
+    placeholder?: string;
 }
 interface FormDatePicker extends FormFieldBase {
     type: 'datepicker';
     value?: Date | null;
     placeholder?: string;
 }
-export type FormField = FormInput | FormTextarea | FormSelect | FormCheckbox | FormToggle | FormRadio | FormComboBox | FormMultiSelect | FormDatePicker;
+interface FormFileUpload extends FormFieldBase {
+    type: 'file';
+    multiple?: boolean;
+    acceptedFileTypes?: string;
+}
+interface FormSegmentedControl extends FormFieldBase {
+    type: 'segment';
+    options: SegmentedControlOption[];
+    value?: string | number;
+}
+export type FormField = FormInput | FormTextarea | FormSelect | FormCheckbox | FormToggle | FormRadio | FormComboBox | FormMultiSelect | FormDatePicker | FormFileUpload | FormSegmentedControl;
 export interface FormTemplateProps {
     fields: FormField[];
     onSubmit: (formData: Record<string, any>) => void;
@@ -68,22 +79,19 @@ export interface FormTemplateProps {
 /**
  * @wizard
  * @name FormTemplate
- * @description A data-driven form builder that renders a grid of input fields from a configuration array, handling internal state and submission.
+ * @description A data-driven form builder that renders a grid of input fields from a configuration array. Now supports File Uploads and Segmented Controls.
  * @category form
  * @tags form, template, builder, input, layout
  * @props
  * - name: fields
  * type: FormField[]
- * description: An array of field definition objects (name, label, type, etc.) that determine the form structure.
+ * description: An array of field definition objects.
  * - name: onSubmit
  * type: (formData: Record<string, any>) => void
- * description: Callback function triggered when the form is submitted, receiving the collected data.
+ * description: Callback function triggered when the form is submitted.
  * - name: className
  * type: string
  * description: Optional additional CSS classes for the form container.
- * - name: children
- * type: React.ReactNode
- * description: Content to render at the bottom of the form, typically used for action buttons like "Save" or "Cancel".
  * @id form-template
  */
 export declare const FormTemplate: React.FC<FormTemplateProps>;

package/dist/src/components/forms/MultiSelect.d.ts

@@ -1,7 +1,7 @@
 import { default as React } from 'react';
 
 export interface MultiSelectOption {
-    value: string;
+    value: string | number;
     label: string;
 }
 export interface MultiSelectProps {
@@ -14,13 +14,8 @@ export interface MultiSelectProps {
     isDisabled?: boolean;
     isLoading?: boolean;
     isSearchable?: boolean;
+    className?: string;
+    error?: boolean;
+    helperText?: string;
 }
-/**
- * @wizard
- * @name MultiSelect
- * @description An enhanced dropdown that allows users to select multiple options from a searchable list.
- * @tags form, input, select, dropdown
- * @category form
- * @id multi-select
- */
 export declare const MultiSelect: React.FC<MultiSelectProps>;

package/dist/src/components/forms/SegmentedControl.d.ts

@@ -6,35 +6,23 @@ export interface SegmentedControlOption {
     disabled?: boolean;
 }
 export interface SegmentedControlProps {
+    /** The list of segments to display. */
     options: SegmentedControlOption[];
+    /** The currently selected value. */
     value: string | number;
+    /** Callback fired when a segment is selected. */
     onChange: (value: any) => void;
+    /** The size of the control. */
     size?: 'sm' | 'md';
+    /** Additional CSS classes. */
     className?: string;
 }
 /**
  * @wizard
  * @name SegmentedControl
- * @description A linear toggle component that functions like a radio group. Ideal for switching between discrete modes (e.g., "Off / Auto / On").
+ * @description A theme-aware linear toggle component. Ideal for switching between discrete modes (e.g., "Map / List").
  * @tags input, toggle, switch, radio, control
- * @category input
- * @props
- * - name: options
- * type: Array<{ label: string, value: string | number }>
- * description: The list of segments to display.
- * - name: value
- * type: string | number
- * description: The currently selected value.
- * - name: onChange
- * type: function
- * description: Callback fired when a segment is selected.
- * - name: size
- * type: 'sm' | 'md'
- * description: The size of the control.
- * default: 'md'
- * - name: className
- * type: string
- * description: Additional CSS classes.
+ * @category form
  * @id segmented-control
  */
 export declare const SegmentedControl: React.FC<SegmentedControlProps>;

package/dist/src/components/forms/Select.d.ts

@@ -4,38 +4,18 @@ export interface SelectOption {
     value: string | number;
     label: string;
 }
-export interface SelectProps extends React.SelectHTMLAttributes<HTMLSelectElement> {
+export interface SelectProps {
     options: SelectOption[];
+    value?: SelectOption | null;
+    onChange: (option: SelectOption | null) => void;
     label?: string;
+    placeholder?: string;
+    isDisabled?: boolean;
+    isLoading?: boolean;
+    isClearable?: boolean;
+    isSearchable?: boolean;
+    className?: string;
+    error?: boolean;
+    helperText?: string;
 }
-/**
- * @wizard
- * @name Select
- * @description A standard HTML select dropdown component for choosing a single option from a list.
- * @tags form, input, dropdown, ui
- * @props
- * - name: options
- * type: { value: string | number; label: string; }[]
- * description: An array of objects defining the selectable options, each with a `value` and `label`.
- * - name: label
- * type: string
- * description: An optional label displayed above the select dropdown.
- * - name: id
- * type: string
- * description: A unique HTML `id` for the select element. Automatically generated if not provided.
- * - name: className
- * type: string
- * description: Optional additional CSS classes for the select element.
- * - name: value
- * type: string | number | readonly string[]
- * description: The currently selected option's value.
- * - name: onChange
- * type: (event: React.ChangeEvent<HTMLSelectElement>) => void
- * description: Callback function triggered when the selected value changes.
- * - name: disabled
- * type: boolean
- * description: If true, the select dropdown will be unclickable.
- * @category form
- * @id select
- */
 export declare const Select: React.FC<SelectProps>;

package/dist/src/components/layout/Card.d.ts

@@ -1,5 +1,7 @@
-import { HTMLAttributes, FC } from 'react';
+import { default as React } from 'react';
 
+export interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
+}
 /**
  * @wizard
  * @name Card
@@ -15,4 +17,4 @@ import { HTMLAttributes, FC } from 'react';
  * @category layout
  * @id card
  */
-export declare const Card: FC<HTMLAttributes<HTMLDivElement>>;
+export declare const Card: React.ForwardRefExoticComponent<CardProps & React.RefAttributes<HTMLDivElement>>;

package/dist/src/components/layout/Sidebar.d.ts

@@ -1,37 +1,45 @@
-import { default as React, ReactNode } from 'react';
+import { default as React } from 'react';
+import { IconName } from '../ui/Icon';
 
-interface SidebarContextProps {
-    isOpen: boolean;
-    setIsOpen: (isOpen: boolean) => void;
-    toggle: () => void;
+export interface SidebarItem {
+    id: string;
+    label: string;
+    icon: IconName;
+    href?: string;
+    onClick?: () => void;
+    subItems?: Omit<SidebarItem, 'icon'>[];
+    badge?: string | number;
+}
+export interface SidebarUser {
+    name: string;
+    email: string;
+    avatarUrl?: string;
+}
+export interface SidebarProps {
+    items: SidebarItem[];
+    user?: SidebarUser;
+    className?: string;
+    logo?: React.ReactNode;
+    activeItemId?: string;
+    onNavigate?: (item: SidebarItem) => void;
+    footerSlot?: React.ReactNode;
 }
-export declare const useSidebar: () => SidebarContextProps;
-export declare const SidebarProvider: ({ children }: {
-    children: ReactNode;
-}) => import("react/jsx-runtime").JSX.Element;
 /**
  * @wizard
  * @name Sidebar
- * @description A collapsible, responsive sidebar component.
+ * @description A collapsible sidebar navigation component with support for branding, navigation items, and user profile.
+ * @tags layout, navigation, sidebar
  * @props
- * @prop {React.ReactNode} children - The content of the sidebar.
+ * - name: items
+ * type: SidebarItem[]
+ * description: Array of navigation items.
+ * - name: user
+ * type: SidebarUser
+ * description: User profile information for the footer.
+ * - name: activeItemId
+ * type: string
+ * description: ID of the currently active navigation item.
+ * @category layout
  * @id sidebar
  */
-export declare const Sidebar: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
-export declare const SidebarHeader: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
-export declare const SidebarContent: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
-export declare const SidebarGroup: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
-export declare const SidebarFooter: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
-export declare const SidebarMenu: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLElement> & React.RefAttributes<HTMLElement>>;
-interface SidebarMenuItemProps extends React.HTMLAttributes<HTMLDivElement> {
-    icon?: React.ReactNode;
-    badge?: React.ReactNode;
-    tooltip?: string;
-    href?: string;
-    isActive?: boolean;
-    as?: React.ElementType;
-    end?: boolean;
-}
-export declare const SidebarMenuItem: React.ForwardRefExoticComponent<SidebarMenuItemProps & React.RefAttributes<HTMLDivElement>>;
-export declare const SidebarTrigger: () => import("react/jsx-runtime").JSX.Element;
-export {};
+export declare const Sidebar: React.FC<SidebarProps>;

package/dist/src/components/layout/StorySidebarContent.d.ts

@@ -1 +1,8 @@
-export declare const StorySidebarContent: () => import("react/jsx-runtime").JSX.Element;
+import { SidebarItem } from './Sidebar';
+
+export declare const mockItems: SidebarItem[];
+export declare const mockUser: {
+    name: string;
+    email: string;
+    avatarUrl: string;
+};

package/dist/src/components/ui/Avatar.d.ts

@@ -10,10 +10,6 @@ interface AvatarProps {
     /** Optional additional CSS classes. */
     className?: string;
 }
-/**
- * A component for displaying a user's avatar. It shows an image if a `src`
- * is provided, otherwise it falls back to the user's initials.
- */
 /**
  * @wizard
  * @name Avatar

package/dist/src/components/ui/Badge.d.ts

@@ -2,7 +2,7 @@ import { default as React } from 'react';
 import { VariantProps } from 'class-variance-authority';
 
 declare const badgeVariants: (props?: ({
-    variant?: "primary" | "secondary" | "danger" | "success" | "outline" | null | undefined;
+    variant?: "outline" | "primary" | "secondary" | "danger" | "success" | "warning" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
 export interface BadgeProps extends React.HTMLAttributes<HTMLDivElement>, VariantProps<typeof badgeVariants> {
 }
@@ -13,13 +13,16 @@ export interface BadgeProps extends React.HTMLAttributes<HTMLDivElement>, Varian
  * @tags ui, label, indicator
  * @props
  * - name: variant
- * type: "'primary' | 'secondary' | 'danger' | 'success' | 'outline'"
+ * type: "'primary' | 'secondary' | 'danger' | 'success' | 'warning' | 'outline'"
  * description: The visual style of the badge.
  * - name: children
  * type: React.ReactNode
  * description: The content to display inside the badge.
+ * - name: className
+ * type: string
+ * description: Optional additional CSS classes.
  * @category ui
  * @id badge
  */
-declare function Badge({ className, variant, ...props }: BadgeProps): import("react/jsx-runtime").JSX.Element;
-export { Badge, badgeVariants };
+export declare const Badge: React.ForwardRefExoticComponent<BadgeProps & React.RefAttributes<HTMLDivElement>>;
+export { badgeVariants };

package/dist/src/components/ui/Button.d.ts

@@ -31,7 +31,7 @@ import { IconName } from './Icon';
  * @id button
  */
 declare const buttonVariants: (props?: ({
-    variant?: "link" | "ghost" | "primary" | "secondary" | "danger" | "outline" | "accent" | null | undefined;
+    variant?: "link" | "ghost" | "outline" | "primary" | "secondary" | "danger" | "accent" | null | undefined;
     size?: "sm" | "md" | "lg" | "icon" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
 export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {