npm - @dimaan/ui - Versions diffs - 0.0.7 → 0.0.9 - Mend

@dimaan/ui 0.0.7 → 0.0.9

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/dist/index.d.cts CHANGED Viewed

@@ -76,6 +76,51 @@ interface AppShellProps extends Pick<DashboardLayoutProps, 'defaultCollapsed' |
     sidebarFooter?: ReactNode;
     children: ReactNode;
 }
+/**
+ * Opinionated dashboard shell that combines `<DashboardLayout>` + `<Sidebar>` + `<Header>`
+ * with a flat `nav` array. Hosts `<DirectionProvider>` so any Radix-based component
+ * inside (Select, future Tooltip/Popover/etc.) auto-detects direction from `<html dir>`.
+ *
+ * For more complex layouts (custom sections, dividers, multi-row headers), compose
+ * the underlying primitives (`Sidebar` + `SidebarNav` + `DashboardHeader`) directly.
+ *
+ * @example Basic usage
+ * ```tsx
+ * <AppShell
+ *   brand={{ logo: <Logo />, name: 'Acme' }}
+ *   nav={[
+ *     { key: 'home', label: 'Home', href: '/', icon: <Home /> },
+ *     {
+ *       key: 'settings',
+ *       label: 'Settings',
+ *       icon: <Settings />,
+ *       items: [
+ *         { key: 'profile', label: 'Profile', href: '/settings/profile' },
+ *         { key: 'team', label: 'Team', href: '/settings/team' },
+ *       ],
+ *     },
+ *   ]}
+ *   title="Dashboard"
+ *   searchPlaceholder="Search…"
+ *   headerActions={<UserMenu />}
+ *   sidebarFooter={<UserBadge />}
+ * >
+ *   <Routes>...</Routes>
+ * </AppShell>
+ * ```
+ *
+ * @example With React Router Link integration via render prop
+ * ```tsx
+ * const nav = [{
+ *   key: 'home',
+ *   label: 'Home',
+ *   icon: <Home />,
+ *   render: ({ children, className, ...rest }) => (
+ *     <Link to="/" className={className} {...rest}>{children}</Link>
+ *   ),
+ * }];
+ * ```
+ */
 declare function AppShell({ brand, nav, title, searchPlaceholder, onSearch, headerActions, sidebarFooter, defaultCollapsed, collapsed, onCollapsedChange, children, }: AppShellProps): react_jsx_runtime.JSX.Element;
 interface AvatarProps extends HTMLAttributes<HTMLSpanElement> {
@@ -111,6 +156,29 @@ interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
      */
     asChild?: boolean;
 }
+/**
+ * Polymorphic button with 6 variants, 4 sizes, and a built-in loading state.
+ * Supports the `asChild` slot pattern for routing-library `<Link>` integration.
+ *
+ * @example Default usage
+ * ```tsx
+ * <Button onClick={handleSave}>Save</Button>
+ * ```
+ *
+ * @example Variant + size + loading
+ * ```tsx
+ * <Button variant="outline" size="sm" loading={isSubmitting}>
+ *   Cancel
+ * </Button>
+ * ```
+ *
+ * @example asChild — wrap a router Link without a wrapper element
+ * ```tsx
+ * <Button asChild variant="ghost">
+ *   <Link to="/settings">Open settings</Link>
+ * </Button>
+ * ```
+ */
 declare const Button: react.ForwardRefExoticComponent<ButtonProps & react.RefAttributes<HTMLButtonElement>>;
 type CheckboxSize = 'sm' | 'md';
@@ -134,8 +202,16 @@ interface FieldRHFProps<TValues extends FieldValues = FieldValues, TName extends
     /** Path to the field within the form values. */
     name: TName;
 }
+/**
+ * `vertical` (default) — label on top, control below, helper/error under.
+ * `horizontal` — label on start, control on end (same row); helper/error below.
+ *
+ * Use `horizontal` for boolean controls (Switch, Checkbox) where the universal
+ * pattern is "label · toggle" rather than "label / toggle below".
+ */
+type FieldOrientation = 'vertical' | 'horizontal';
 interface FieldLayoutProps {
-    /** Label rendered above the control. */
+    /** Label rendered with the control. Position depends on `orientation`. */
     label?: ReactNode;
     /** Helper text rendered under the control when there's no error. */
     description?: ReactNode;
@@ -145,6 +221,8 @@ interface FieldLayoutProps {
     disabled?: boolean;
     /** Stretch the wrapper to fill its parent. Defaults to `true`. */
     fullWidth?: boolean;
+    /** Layout direction. `vertical` (default) for inputs; `horizontal` for switches/checkboxes. */
+    orientation?: FieldOrientation;
     /** Class applied to the outer wrapper. */
     className?: string;
     /** The single control element to wrap. Receives id + aria + (in RHF mode) field props. */
@@ -253,6 +331,32 @@ interface InputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'
     /** Class applied to the field container (`<label>` block). */
     containerClassName?: string;
 }
+/**
+ * Text input with optional label, helper text, error message, and leading/trailing icons.
+ * Works standalone (uses `label`/`helperText`/`error` props) OR wrapped inside `<Field>`
+ * (id and aria-* are injected by Field via `cloneElement`).
+ *
+ * @example Standalone with label + helper
+ * ```tsx
+ * <Input label="Email" helperText="We'll never share it." type="email" />
+ * ```
+ *
+ * @example With icons
+ * ```tsx
+ * <Input
+ *   label="Search"
+ *   leadingIcon={<Search />}
+ *   trailingIcon={<X onClick={clear} />}
+ * />
+ * ```
+ *
+ * @example Inside a Field (RHF + Zod)
+ * ```tsx
+ * <Field name="email" label="Email" required>
+ *   <Input type="email" />
+ * </Field>
+ * ```
+ */
 declare const Input: react.ForwardRefExoticComponent<InputProps & react.RefAttributes<HTMLInputElement>>;
 interface LanguageOption<TCode extends string = string> {
@@ -268,6 +372,101 @@ interface LanguageSwitcherProps<TCode extends string = string> extends Omit<Fiel
 }
 declare function LanguageSwitcher<TCode extends string = string>({ languages, value, onChange, ariaLabel, className, ...props }: LanguageSwitcherProps<TCode>): react_jsx_runtime.JSX.Element;
+type SelectVariant = 'default' | 'filled' | 'ghost';
+type SelectSize = 'sm' | 'md' | 'lg';
+declare const selectVariantClass: Record<SelectVariant, string>;
+/**
+ * `pe-*` is wider than `ps-*` to leave room for the chevron icon. Logical
+ * properties keep RTL working free.
+ */
+declare const selectSizeClass: Record<SelectSize, string>;
+declare const selectBaseClass = "group/select relative inline-flex w-full items-center text-foreground outline-none transition-[background-color,border-color,box-shadow] focus:ring-2 focus:ring-ring/40 focus:ring-offset-1 focus:ring-offset-background aria-[invalid=true]:border-destructive aria-[invalid=true]:focus:ring-destructive/40 disabled:pointer-events-none disabled:opacity-50 cursor-pointer data-[placeholder]:text-muted-foreground";
+interface SelectOption {
+    value: string;
+    label: string;
+    disabled?: boolean;
+}
+interface SelectGroup {
+    label: string;
+    options: SelectOption[];
+}
+/**
+ * `options` accepts either a flat list of options OR a list of groups.
+ * Use `children` for full Radix composition (Select.Item, Select.Separator…).
+ */
+type SelectOptions = SelectOption[] | SelectGroup[];
+interface SelectProps {
+    variant?: SelectVariant;
+    /** Visual size. Named `selectSize` to mirror Input's `inputSize`. */
+    selectSize?: SelectSize;
+    /** Declarative options (flat or grouped). When `children` is provided it wins. */
+    options?: SelectOptions;
+    /** Placeholder shown when no value is selected. */
+    placeholder?: string;
+    /** Controlled value. */
+    value?: string;
+    /** Initial value for uncontrolled usage. */
+    defaultValue?: string;
+    /** Radix-style change handler — receives the new value directly. */
+    onValueChange?: (value: string) => void;
+    /**
+     * Synthetic-event handler for compatibility with `react-hook-form`'s
+     * `field.onChange` and other consumers that expect a `ChangeEvent`-shaped
+     * object. Both this and `onValueChange` fire on selection.
+     */
+    onChange?: (event: ChangeEvent<HTMLSelectElement>) => void;
+    /** Called when focus leaves the trigger. */
+    onBlur?: () => void;
+    /** Form name (for native form submission). */
+    name?: string;
+    /** Disables the trigger. */
+    disabled?: boolean;
+    /** Marks the underlying form input as required. */
+    required?: boolean;
+    /** Override id (otherwise auto-generated via useId). */
+    id?: string;
+    /** Class applied to the trigger button. */
+    className?: string;
+    'aria-invalid'?: boolean | 'true' | 'false';
+    'aria-describedby'?: string;
+    'aria-label'?: string;
+    /** Radix children — used for advanced composition (Select.Group, etc.). */
+    children?: ReactNode;
+}
+/**
+ * Dropdown select built on `@radix-ui/react-select`. Renders only the trigger
+ * button + Radix popup — wrap it in `<Field label="…">` to add a label, helper
+ * text, error, and aria wiring.
+ *
+ * @example Inside a Field (RHF + Zod)
+ * ```tsx
+ * <Field name="country" label="Country" required>
+ *   <Select options={COUNTRIES} placeholder="Pick one" />
+ * </Field>
+ * ```
+ *
+ * @example Bare in a filter bar (no label)
+ * ```tsx
+ * <Select
+ *   value={status}
+ *   onValueChange={setStatus}
+ *   options={STATUS_OPTIONS}
+ *   placeholder="Status"
+ *   aria-label="Status filter"
+ * />
+ * ```
+ *
+ * @example Grouped options
+ * ```tsx
+ * <Select options={[
+ *   { label: 'GCC', options: [{ value: 'sa', label: 'Saudi Arabia' }] },
+ *   { label: 'Levant', options: [{ value: 'jo', label: 'Jordan' }] },
+ * ]} />
+ * ```
+ */
+declare const Select: react.ForwardRefExoticComponent<SelectProps & react.RefAttributes<HTMLButtonElement>>;
 type SidebarProps = HTMLAttributes<HTMLElement>;
 declare function Sidebar({ className, children, ...props }: SidebarProps): react_jsx_runtime.JSX.Element;
@@ -320,6 +519,82 @@ interface SidebarNavItemProps extends AnchorHTMLAttributes<HTMLAnchorElement> {
 }
 declare function SidebarNavItem({ icon, active, label, endSlot, className, children, render, ...props }: SidebarNavItemProps): react_jsx_runtime.JSX.Element;
+type SwitchSize = 'sm' | 'md' | 'lg';
+/**
+ * Each size is a tuple: track dimensions + thumb size + thumb travel distance.
+ * Track is `w` x `h`; thumb is `w/h size-X`; travel is the translation distance
+ * when checked (= track width − thumb size − padding).
+ */
+declare const switchTrackClass: Record<SwitchSize, string>;
+declare const switchThumbClass: Record<SwitchSize, string>;
+declare const switchTrackBaseClass = "relative inline-flex shrink-0 cursor-pointer items-center rounded-full border-2 border-transparent bg-input transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring/40 focus-visible:ring-offset-2 focus-visible:ring-offset-background disabled:cursor-not-allowed disabled:opacity-50 data-[state=checked]:bg-primary aria-[invalid=true]:ring-2 aria-[invalid=true]:ring-destructive/40";
+declare const switchThumbBaseClass = "pointer-events-none block rounded-full bg-background shadow-sm ring-0 transition-transform";
+interface SwitchProps {
+    /** Visual size. */
+    switchSize?: SwitchSize;
+    /** Controlled checked state (Radix-style). */
+    checked?: boolean;
+    /** Initial checked state for uncontrolled usage. */
+    defaultChecked?: boolean;
+    /** Radix-style change handler — receives the new boolean directly. */
+    onCheckedChange?: (checked: boolean) => void;
+    /**
+     * Form-library compatibility props. `value` mirrors what `<Field>` injects
+     * (RHF passes `field.value` as a boolean). `onChange` fires alongside
+     * `onCheckedChange` with a synthetic event so `field.onChange` works too.
+     */
+    value?: boolean | string | number;
+    onChange?: (event: ChangeEvent<HTMLButtonElement>) => void;
+    onBlur?: () => void;
+    /** Form name for native form submission. */
+    name?: string;
+    /** Disable interaction. */
+    disabled?: boolean;
+    /** Mark required for form validation. */
+    required?: boolean;
+    /** Override id (otherwise auto-generated via useId). */
+    id?: string;
+    /** Class on the track (the switch itself). */
+    className?: string;
+    'aria-label'?: string;
+    'aria-describedby'?: string;
+    'aria-invalid'?: boolean | 'true' | 'false';
+}
+/**
+ * Boolean toggle built on `@radix-ui/react-switch`. Renders only the track +
+ * thumb — wrap it in `<Field orientation="horizontal" label="…">` to add a
+ * label, helper text, error, and aria wiring without duplicating that logic
+ * inside every form control.
+ *
+ * @example Inside a Field (RHF + Zod)
+ * ```tsx
+ * <Field name="darkMode" label="Dark mode" orientation="horizontal">
+ *   <Switch />
+ * </Field>
+ * ```
+ *
+ * @example Bare in a settings list (custom layout)
+ * ```tsx
+ * <ul className="divide-y divide-border">
+ *   <li className="flex items-center justify-between py-3">
+ *     <span>Email digest</span>
+ *     <Switch checked={digest} onCheckedChange={setDigest} aria-label="Email digest" />
+ *   </li>
+ * </ul>
+ * ```
+ *
+ * @example Standalone controlled
+ * ```tsx
+ * <Switch
+ *   checked={enabled}
+ *   onCheckedChange={setEnabled}
+ *   aria-label="Enable notifications"
+ * />
+ * ```
+ */
+declare const Switch: react.ForwardRefExoticComponent<SwitchProps & react.RefAttributes<HTMLButtonElement>>;
 type TableSize = 'sm' | 'md' | 'lg';
 interface TableSizeClasses {
     /** Applied to <tr> when needed (currently empty — present for symmetry). */
@@ -457,6 +732,31 @@ interface TextareaProps extends Omit<TextareaHTMLAttributes<HTMLTextAreaElement>
     /** Class applied to the field container (`<label>` block). */
     containerClassName?: string;
 }
+/**
+ * Multi-line text input with the same label/helper/error/aria contract as `<Input>`.
+ * Works standalone OR wrapped inside `<Field>`.
+ *
+ * @example Standalone
+ * ```tsx
+ * <Textarea label="Bio" helperText="Up to 280 characters." rows={4} />
+ * ```
+ *
+ * @example With error + custom resize
+ * ```tsx
+ * <Textarea
+ *   label="Notes"
+ *   error={errors.notes?.message}
+ *   resize="vertical"
+ * />
+ * ```
+ *
+ * @example Inside a Field (RHF + Zod)
+ * ```tsx
+ * <Field name="bio" label="Bio">
+ *   <Textarea rows={4} />
+ * </Field>
+ * ```
+ */
 declare const Textarea: react.ForwardRefExoticComponent<TextareaProps & react.RefAttributes<HTMLTextAreaElement>>;
 type Direction = 'ltr' | 'rtl';
@@ -464,4 +764,4 @@ declare function useDirection(): Direction;
 declare function cn(...inputs: ClassValue[]): string;
-export { AppShell, type AppShellBrand, type AppShellNavGroup, type AppShellNavItem, type AppShellProps, Avatar, type AvatarProps, Button, type ButtonProps, type ButtonSize, type ButtonVariant, Checkbox, type CheckboxProps, type CheckboxSize, type Column, type ColumnAlign, DashboardContent, type DashboardContentProps, DashboardHeader, type DashboardHeaderProps, DashboardLayout, type DashboardLayoutContextValue, type DashboardLayoutProps, DashboardMain, type DashboardMainProps, type Direction, Field, type FieldProps, type FieldRHFProps, HeaderActions, type HeaderActionsProps, HeaderCollapseTrigger, type HeaderCollapseTriggerProps, HeaderMobileTrigger, type HeaderMobileTriggerProps, HeaderSearch, type HeaderSearchProps, HeaderTitle, type HeaderTitleProps, Input, type InputProps, type InputSize, type InputVariant, type LanguageOption, LanguageSwitcher, type LanguageSwitcherProps, type PaginationState, type RowSelectionState, Sidebar, SidebarFooter, type SidebarFooterProps, SidebarGroup, type SidebarGroupProps, SidebarHeader, type SidebarHeaderProps, SidebarNav, SidebarNavGroup, type SidebarNavGroupProps, SidebarNavItem, type SidebarNavItemProps, type SidebarNavItemRenderProps, type SidebarNavProps, type SidebarProps, type SortDirection, type SortState, type SortableValue, Table, type TableProps, type TableSize, type TableSizeClasses, Textarea, type TextareaProps, type TextareaResize, type TextareaSize, type TextareaVariant, buttonBaseClass, buttonSizeClass, buttonVariantClass, cn, inputBaseClass, inputSizeClass, inputVariantClass, alignClass as tableAlignClass, tableBaseClass, selectedRowClass as tableSelectedRowClass, tableSizeClass, sortIconClass as tableSortIconClass, textareaBaseClass, textareaResizeClass, textareaSizeClass, textareaVariantClass, useDashboardLayout, useDirection };
+export { AppShell, type AppShellBrand, type AppShellNavGroup, type AppShellNavItem, type AppShellProps, Avatar, type AvatarProps, Button, type ButtonProps, type ButtonSize, type ButtonVariant, Checkbox, type CheckboxProps, type CheckboxSize, type Column, type ColumnAlign, DashboardContent, type DashboardContentProps, DashboardHeader, type DashboardHeaderProps, DashboardLayout, type DashboardLayoutContextValue, type DashboardLayoutProps, DashboardMain, type DashboardMainProps, type Direction, Field, type FieldOrientation, type FieldProps, type FieldRHFProps, HeaderActions, type HeaderActionsProps, HeaderCollapseTrigger, type HeaderCollapseTriggerProps, HeaderMobileTrigger, type HeaderMobileTriggerProps, HeaderSearch, type HeaderSearchProps, HeaderTitle, type HeaderTitleProps, Input, type InputProps, type InputSize, type InputVariant, type LanguageOption, LanguageSwitcher, type LanguageSwitcherProps, type PaginationState, type RowSelectionState, Select, type SelectOption, type SelectProps, type SelectSize, type SelectVariant, Sidebar, SidebarFooter, type SidebarFooterProps, SidebarGroup, type SidebarGroupProps, SidebarHeader, type SidebarHeaderProps, SidebarNav, SidebarNavGroup, type SidebarNavGroupProps, SidebarNavItem, type SidebarNavItemProps, type SidebarNavItemRenderProps, type SidebarNavProps, type SidebarProps, type SortDirection, type SortState, type SortableValue, Switch, type SwitchProps, type SwitchSize, Table, type TableProps, type TableSize, type TableSizeClasses, Textarea, type TextareaProps, type TextareaResize, type TextareaSize, type TextareaVariant, buttonBaseClass, buttonSizeClass, buttonVariantClass, cn, inputBaseClass, inputSizeClass, inputVariantClass, selectBaseClass, selectSizeClass, selectVariantClass, switchThumbBaseClass, switchThumbClass, switchTrackBaseClass, switchTrackClass, alignClass as tableAlignClass, tableBaseClass, selectedRowClass as tableSelectedRowClass, tableSizeClass, sortIconClass as tableSortIconClass, textareaBaseClass, textareaResizeClass, textareaSizeClass, textareaVariantClass, useDashboardLayout, useDirection };