@mohasinac/ui 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,829 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React, { ReactNode } from 'react';
+import { PaginationConfig, TableColumn, TableConfig } from '@mohasinac/contracts';
+export { DEFAULT_PAGINATION_CONFIG, DEFAULT_STICKY_CONFIG, DEFAULT_TABLE_CONFIG, PaginationConfig, StickyConfig, TableConfig, TableViewMode, mergeTableConfig } from '@mohasinac/contracts';
+
+/**
+ * Semantic HTML Wrapper Components
+ *
+ * Thin wrappers around HTML5 semantic elements.
+ * Using these instead of raw tags enables:
+ *   - Future one-place theming (add default padding/colour here, it applies everywhere)
+ *   - Enforced accessibility attributes (Nav requires aria-label)
+ *   - Consistent documentation / IDE autocomplete
+ *   - Clean migration path if element defaults change
+ *
+ * All components pass through every standard HTML attribute via `...props`.
+ * Style via `className` using Tailwind CSS classes.
+ *
+ * @example
+ * ```tsx
+ * import { Section, Article, Main, Aside, Nav, Ul, Ol, Li } from '@mohasinac/ui';
+ *
+ * <Main className="max-w-7xl mx-auto px-4">
+ *   <Section className="py-12">
+ *     <Article>...</Article>
+ *   </Section>
+ *   <Aside className="w-64 shrink-0">...</Aside>
+ * </Main>
+ *
+ * <Nav aria-label="Main navigation">
+ *   <Ul className="flex gap-4">
+ *     <Li>Products</Li>
+ *   </Ul>
+ * </Nav>
+ * ```
+ */
+/**
+ * Semantic `<section>` element.
+ * Use for thematically grouped content that would appear in an outline.
+ * Prefer this over a plain `<div>` when the block has a heading.
+ */
+interface SectionProps extends React.HTMLAttributes<HTMLElement> {
+    children: React.ReactNode;
+}
+declare const Section: React.ForwardRefExoticComponent<SectionProps & React.RefAttributes<HTMLElement>>;
+/**
+ * Semantic `<article>` element.
+ * Use for self-contained compositions: blog posts, product cards, reviews, forum posts.
+ */
+interface ArticleProps extends React.HTMLAttributes<HTMLElement> {
+    children?: React.ReactNode;
+}
+declare function Article({ className, children, ...props }: ArticleProps): react_jsx_runtime.JSX.Element;
+/**
+ * Semantic `<main>` element.
+ * Wraps the primary content of the document. Should appear only once per page.
+ */
+interface MainProps extends React.HTMLAttributes<HTMLElement> {
+    children: React.ReactNode;
+}
+declare function Main({ className, children, ...props }: MainProps): react_jsx_runtime.JSX.Element;
+/**
+ * Semantic `<aside>` element.
+ * Use for supplementary content tangentially related to the main content:
+ * sidebars, callout boxes, related-link panels.
+ */
+interface AsideProps extends React.HTMLAttributes<HTMLElement> {
+    children: React.ReactNode;
+}
+declare const Aside: React.ForwardRefExoticComponent<AsideProps & React.RefAttributes<HTMLElement>>;
+/**
+ * Semantic `<nav>` element with enforced `aria-label`.
+ *
+ * Every `<nav>` on a page MUST have a unique `aria-label` so assistive
+ * technologies can distinguish between multiple navigation landmarks.
+ *
+ * @example
+ * ```tsx
+ * <Nav aria-label="Breadcrumb">...</Nav>
+ * <Nav aria-label="Product categories">...</Nav>
+ * ```
+ */
+interface NavProps extends React.HTMLAttributes<HTMLElement> {
+    /** REQUIRED — describes the purpose of this navigation region for screen readers. */
+    "aria-label": string;
+    children: React.ReactNode;
+}
+declare function Nav({ className, children, ...props }: NavProps): react_jsx_runtime.JSX.Element;
+/**
+ * Semantic `<header>` element for block-level component headers.
+ * Use inside `Section`, `Article`, or card bodies — NOT as the page-level header.
+ *
+ * @example
+ * ```tsx
+ * <Article>
+ *   <BlockHeader className="mb-4">
+ *     <Heading level={2}>Post title</Heading>
+ *   </BlockHeader>
+ * </Article>
+ * ```
+ */
+interface BlockHeaderProps extends React.HTMLAttributes<HTMLElement> {
+    children: React.ReactNode;
+}
+declare function BlockHeader({ className, children, ...props }: BlockHeaderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Semantic `<footer>` element for block-level component footers.
+ * Use inside `Section`, `Article`, or card bodies — NOT as the page-level footer.
+ */
+interface BlockFooterProps extends React.HTMLAttributes<HTMLElement> {
+    children: React.ReactNode;
+}
+declare function BlockFooter({ className, children, ...props }: BlockFooterProps): react_jsx_runtime.JSX.Element;
+/**
+ * Semantic `<ul>` (unordered list) element.
+ *
+ * @example
+ * ```tsx
+ * <Ul className="space-y-2">
+ *   <Li>Item one</Li>
+ *   <Li>Item two</Li>
+ * </Ul>
+ * ```
+ */
+interface UlProps extends React.HTMLAttributes<HTMLUListElement> {
+    children: React.ReactNode;
+}
+declare function Ul({ className, children, ...props }: UlProps): react_jsx_runtime.JSX.Element;
+/**
+ * Semantic `<ol>` (ordered list) element.
+ *
+ * @example
+ * ```tsx
+ * <Ol className="list-decimal pl-4 space-y-1">
+ *   <Li>Step one</Li>
+ *   <Li>Step two</Li>
+ * </Ol>
+ * ```
+ */
+interface OlProps extends React.HTMLAttributes<HTMLOListElement> {
+    children: React.ReactNode;
+}
+declare function Ol({ className, children, ...props }: OlProps): react_jsx_runtime.JSX.Element;
+/**
+ * Semantic `<li>` (list item) element. Use inside `Ul` or `Ol`.
+ */
+interface LiProps extends React.LiHTMLAttributes<HTMLLIElement> {
+    children: React.ReactNode;
+}
+declare function Li({ className, children, ...props }: LiProps): react_jsx_runtime.JSX.Element;
+
+interface HeadingProps extends React.HTMLAttributes<HTMLHeadingElement> {
+    level?: 1 | 2 | 3 | 4 | 5 | 6;
+    variant?: "primary" | "secondary" | "muted" | "none";
+    children: React.ReactNode;
+}
+declare function Heading({ level, variant, className, children, ...props }: HeadingProps): react_jsx_runtime.JSX.Element;
+interface TextProps extends React.HTMLAttributes<HTMLParagraphElement> {
+    variant?: "primary" | "secondary" | "muted" | "error" | "success" | "none";
+    size?: "xs" | "sm" | "base" | "lg" | "xl";
+    weight?: "normal" | "medium" | "semibold" | "bold";
+    children: React.ReactNode;
+}
+declare function Text({ variant, size, weight, className, children, ...props }: TextProps): react_jsx_runtime.JSX.Element;
+interface LabelProps extends React.LabelHTMLAttributes<HTMLLabelElement> {
+    required?: boolean;
+    children: React.ReactNode;
+}
+declare function Label({ required, className, children, ...props }: LabelProps): react_jsx_runtime.JSX.Element;
+interface CaptionProps extends React.HTMLAttributes<HTMLSpanElement> {
+    /** "default" — muted grey (default); "accent" — indigo, semibold; "inverse" — light indigo for use on dark indigo backgrounds */
+    variant?: "default" | "accent" | "inverse";
+    children: React.ReactNode;
+}
+declare function Caption({ variant, className, children, ...props }: CaptionProps): react_jsx_runtime.JSX.Element;
+/**
+ * Inline wrapper for styled text fragments. Use instead of a raw `<span>`.
+ * When `variant` is "inherit" (default) the element carries no colour classes
+ * so it blends with its parent — perfect for purely structural/CSS wrappers.
+ *
+ * @example
+ * ```tsx
+ * <Span className="bg-gradient-to-r from-indigo-500 to-purple-500 bg-clip-text text-transparent">
+ *   Highlighted
+ * </Span>
+ *
+ * <Span variant="error" weight="semibold">Required</Span>
+ * ```
+ */
+interface SpanProps extends React.HTMLAttributes<HTMLSpanElement> {
+    /** Colour variant. "inherit" (default) applies no colour class. */
+    variant?: "inherit" | "primary" | "secondary" | "muted" | "error" | "success" | "accent";
+    size?: "xs" | "sm" | "base" | "lg" | "xl";
+    weight?: "normal" | "medium" | "semibold" | "bold";
+    children?: React.ReactNode;
+}
+declare function Span({ variant, size, weight, className, children, ...props }: SpanProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Spinner — generic loading indicator.
+ *
+ * Extracted from src/components/ui/Spinner.tsx for @mohasinac/ui.
+ * No app-specific imports; pure Tailwind CSS.
+ */
+interface SpinnerProps {
+    size?: "sm" | "md" | "lg" | "xl";
+    variant?: "primary" | "white" | "current";
+    className?: string;
+    label?: string;
+}
+declare function Spinner({ size, variant, className, label, }: SpinnerProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Skeleton — content placeholder with pulse or wave animation.
+ *
+ * Extracted from src/components/ui/Skeleton.tsx for @mohasinac/ui.
+ * Wave animation uses a plain <style> element (no styled-jsx dependency).
+ */
+interface SkeletonProps {
+    variant?: "text" | "circular" | "rectangular";
+    width?: string | number;
+    height?: string | number;
+    className?: string;
+    animation?: "pulse" | "wave" | "none";
+}
+declare function Skeleton({ variant, width, height, className, animation, }: SkeletonProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Button — versatile button with multiple variants, sizes, and loading state.
+ *
+ * Extracted from src/components/ui/Button.tsx for @mohasinac/ui.
+ * Theme values inlined from THEME_CONSTANTS.button and THEME_CONSTANTS.colors.button.
+ */
+declare const UI_BUTTON: {
+    readonly base: "inline-flex items-center justify-center font-medium rounded-xl transition-all duration-200 focus:outline-none focus:ring-2 focus:ring-offset-2 disabled:opacity-50 disabled:cursor-not-allowed";
+    readonly active: "active:scale-95";
+    readonly variants: {
+        readonly primary: "bg-primary-600 text-white hover:bg-primary-700 active:bg-primary-800 shadow-sm focus:ring-primary-500/30 dark:bg-secondary-500 dark:text-white dark:hover:bg-secondary-400 dark:active:bg-secondary-600 dark:focus:ring-secondary-400/30";
+        readonly secondary: "bg-primary-700 text-white hover:bg-primary-600 active:bg-primary-800 shadow-md focus:ring-primary-500 dark:bg-secondary-700 dark:text-white dark:hover:bg-secondary-600 dark:active:bg-secondary-800 dark:focus:ring-secondary-500";
+        readonly outline: "border border-zinc-200 dark:border-slate-700 bg-white dark:bg-transparent text-zinc-900 dark:text-zinc-100 hover:bg-zinc-50 dark:hover:bg-slate-800 focus:ring-zinc-400";
+        readonly ghost: "text-zinc-700 dark:text-zinc-300 hover:bg-zinc-100 dark:hover:bg-slate-800 focus:ring-zinc-400";
+        readonly danger: "bg-red-600 text-white hover:bg-red-500 active:bg-red-700 shadow-sm shadow-red-600/10 focus:ring-red-500";
+        readonly warning: "bg-amber-500 text-white hover:bg-amber-400 active:bg-amber-600 shadow-sm shadow-amber-500/10 focus:ring-amber-500";
+    };
+    readonly sizes: {
+        readonly sm: "px-2.5 py-1.5 text-xs sm:px-3 sm:text-sm gap-1.5 min-h-[36px]";
+        readonly md: "px-3 py-2 text-sm sm:px-4 sm:py-2.5 sm:text-base gap-2 min-h-[44px]";
+        readonly lg: "px-4 py-2.5 text-base sm:px-6 sm:py-3 sm:text-lg gap-2.5 min-h-[44px]";
+    };
+};
+interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    variant?: keyof typeof UI_BUTTON.variants;
+    size?: keyof typeof UI_BUTTON.sizes;
+    isLoading?: boolean;
+    children?: React.ReactNode;
+}
+declare function Button({ variant, size, className, isLoading, disabled, children, ...props }: ButtonProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Badge — compact label with ring border variants for status, roles, and categories.
+ *
+ * Extracted from src/components/ui/Badge.tsx for @mohasinac/ui.
+ * Theme values inlined from THEME_CONSTANTS.badge and THEME_CONSTANTS.colors.badge.
+ */
+declare const BADGE_CLASSES: {
+    readonly active: "inline-flex items-center gap-1 px-2.5 py-0.5 text-xs font-semibold rounded-full bg-emerald-50 text-emerald-700 ring-1 ring-emerald-600/20 dark:bg-emerald-900/30 dark:text-emerald-300 dark:ring-emerald-400/20";
+    readonly inactive: "inline-flex items-center gap-1 px-2.5 py-0.5 text-xs font-semibold rounded-full bg-zinc-100 text-zinc-600 ring-1 ring-zinc-500/10 dark:bg-slate-800 dark:text-zinc-400 dark:ring-zinc-400/20";
+    readonly pending: "inline-flex items-center gap-1 px-2.5 py-0.5 text-xs font-semibold rounded-full bg-amber-50 text-amber-700 ring-1 ring-amber-600/20 dark:bg-amber-900/30 dark:text-amber-300 dark:ring-amber-400/20";
+    readonly approved: "inline-flex items-center gap-1 px-2.5 py-0.5 text-xs font-semibold rounded-full bg-emerald-50 text-emerald-700 ring-1 ring-emerald-600/20 dark:bg-emerald-900/30 dark:text-emerald-300 dark:ring-emerald-400/20";
+    readonly rejected: "inline-flex items-center gap-1 px-2.5 py-0.5 text-xs font-semibold rounded-full bg-rose-50 text-rose-700 ring-1 ring-rose-600/20 dark:bg-rose-900/30 dark:text-rose-300 dark:ring-rose-400/20";
+    readonly success: "inline-flex items-center gap-1 px-2.5 py-0.5 text-xs font-semibold rounded-full bg-emerald-50 text-emerald-700 ring-1 ring-emerald-600/20 dark:bg-emerald-900/30 dark:text-emerald-300 dark:ring-emerald-400/20";
+    readonly warning: "inline-flex items-center gap-1 px-2.5 py-0.5 text-xs font-semibold rounded-full bg-amber-50 text-amber-700 ring-1 ring-amber-600/20 dark:bg-amber-900/30 dark:text-amber-300 dark:ring-amber-400/20";
+    readonly danger: "inline-flex items-center gap-1 px-2.5 py-0.5 text-xs font-semibold rounded-full bg-rose-50 text-rose-700 ring-1 ring-rose-600/20 dark:bg-rose-900/30 dark:text-rose-300 dark:ring-rose-400/20";
+    readonly info: "inline-flex items-center gap-1 px-2.5 py-0.5 text-xs font-semibold rounded-full bg-sky-50 text-sky-700 ring-1 ring-sky-600/20 dark:bg-sky-900/30 dark:text-sky-300 dark:ring-sky-400/20";
+    readonly admin: "inline-flex items-center gap-1 px-2.5 py-0.5 text-xs font-semibold rounded-full bg-purple-50 text-purple-700 ring-1 ring-purple-600/20 dark:bg-purple-900/30 dark:text-purple-300 dark:ring-purple-400/20";
+    readonly moderator: "inline-flex items-center gap-1 px-2.5 py-0.5 text-xs font-semibold rounded-full bg-sky-50 text-sky-700 ring-1 ring-sky-600/20 dark:bg-sky-900/30 dark:text-sky-300 dark:ring-sky-400/20";
+    readonly seller: "inline-flex items-center gap-1 px-2.5 py-0.5 text-xs font-semibold rounded-full bg-teal-50 text-teal-700 ring-1 ring-teal-600/20 dark:bg-teal-900/30 dark:text-teal-300 dark:ring-teal-400/20";
+    readonly user: "inline-flex items-center gap-1 px-2.5 py-0.5 text-xs font-semibold rounded-full bg-zinc-100 text-zinc-700 ring-1 ring-zinc-500/10 dark:bg-slate-800 dark:text-zinc-300 dark:ring-zinc-400/20";
+    readonly default: "inline-flex items-center gap-1 px-2.5 py-0.5 text-xs font-semibold rounded-full bg-zinc-100 text-zinc-700 ring-1 ring-zinc-500/10 dark:bg-slate-800 dark:text-zinc-300 dark:ring-zinc-400/20";
+    readonly primary: "inline-flex items-center gap-1 px-2.5 py-0.5 text-xs font-semibold rounded-full bg-primary-100 text-primary-700 dark:bg-primary-900/50 dark:text-primary-300";
+    readonly secondary: "inline-flex items-center gap-1 px-2.5 py-0.5 text-xs font-semibold rounded-full bg-primary-100 text-primary-700 dark:bg-primary-900/50 dark:text-primary-300";
+};
+type BadgeVariant = keyof typeof BADGE_CLASSES;
+interface BadgeProps {
+    children: React.ReactNode;
+    variant?: BadgeVariant;
+    className?: string;
+}
+declare function Badge({ children, variant, className, }: BadgeProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Alert — flexible alert/notification with variant icons and optional dismiss.
+ *
+ * Extracted from src/components/feedback/Alert.tsx for @mohasinac/ui.
+ * Theme values inlined from THEME_CONSTANTS.colors.alert and THEME_CONSTANTS.colors.button.
+ */
+declare const ALERT_STYLES: {
+    readonly info: {
+        readonly container: "bg-sky-50 border-sky-200/80 dark:bg-sky-950/30 dark:border-sky-800/50";
+        readonly icon: "text-sky-600 dark:text-sky-400";
+        readonly title: "text-sky-900 dark:text-sky-200";
+        readonly text: "text-sky-800 dark:text-sky-300";
+    };
+    readonly success: {
+        readonly container: "bg-emerald-50 border-emerald-200/80 dark:bg-emerald-950/30 dark:border-emerald-800/50";
+        readonly icon: "text-emerald-600 dark:text-emerald-400";
+        readonly title: "text-emerald-900 dark:text-emerald-200";
+        readonly text: "text-emerald-800 dark:text-emerald-300";
+    };
+    readonly warning: {
+        readonly container: "bg-amber-50 border-amber-200/80 dark:bg-amber-950/30 dark:border-amber-800/50";
+        readonly icon: "text-amber-600 dark:text-amber-400";
+        readonly title: "text-amber-900 dark:text-amber-200";
+        readonly text: "text-amber-800 dark:text-amber-300";
+    };
+    readonly error: {
+        readonly container: "bg-red-50 border-red-200/80 dark:bg-red-950/30 dark:border-red-800/50";
+        readonly icon: "text-red-600 dark:text-red-400";
+        readonly title: "text-red-900 dark:text-red-200";
+        readonly text: "text-red-800 dark:text-red-300";
+    };
+};
+interface AlertProps {
+    children: React.ReactNode;
+    variant?: keyof typeof ALERT_STYLES;
+    title?: string;
+    onClose?: () => void;
+    className?: string;
+}
+declare function Alert({ children, variant, title, onClose, className, }: AlertProps): react_jsx_runtime.JSX.Element;
+
+interface DividerProps {
+    label?: string;
+    orientation?: "horizontal" | "vertical";
+    className?: string;
+}
+declare function Divider({ label, orientation, className, }: DividerProps): react_jsx_runtime.JSX.Element;
+
+interface ProgressProps {
+    value: number;
+    max?: number;
+    variant?: "primary" | "success" | "warning" | "error";
+    size?: "sm" | "md" | "lg";
+    label?: string;
+    showValue?: boolean;
+    className?: string;
+}
+declare function Progress({ value, max, variant, size, label, showValue, className, }: ProgressProps): react_jsx_runtime.JSX.Element;
+interface IndeterminateProgressProps {
+    variant?: "primary" | "success" | "warning" | "error";
+    size?: "sm" | "md" | "lg";
+    label?: string;
+    className?: string;
+}
+declare function IndeterminateProgress({ variant, size, label, className, }: IndeterminateProgressProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Pagination — smart ellipsis pagination with prev/next chevrons.
+ *
+ * Accepts either individual props OR a `paginationConfig` object
+ * (merged with DEFAULT_PAGINATION_CONFIG). Individual props take precedence.
+ */
+interface PaginationProps {
+    currentPage: number;
+    totalPages: number;
+    onPageChange: (page: number) => void;
+    /**
+     * Composable pagination config. Merged with DEFAULT_PAGINATION_CONFIG.
+     * Individual flat props override this.
+     */
+    paginationConfig?: Partial<PaginationConfig>;
+    /** Max visible page buttons before ellipsis kicks in. Default: 7 */
+    maxVisible?: number;
+    showFirstLast?: boolean;
+    showPrevNext?: boolean;
+    disabled?: boolean;
+    size?: "sm" | "md" | "lg";
+    className?: string;
+}
+declare function Pagination({ currentPage, totalPages, onPageChange, paginationConfig, maxVisible: maxVisibleProp, showFirstLast: showFirstLastProp, showPrevNext: showPrevNextProp, disabled, size: sizeProp, className, }: PaginationProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * StatusBadge — semantic color map for order/payment/review/ticket status strings.
+ *
+ * Wraps @mohasinac/ui Badge with a pre-defined status → variant mapping.
+ * No app-specific imports.
+ */
+type OrderStatus = "pending" | "confirmed" | "processing" | "shipped" | "delivered" | "cancelled" | "refunded" | "failed";
+type PaymentStatus = "pending" | "paid" | "failed" | "refunded" | "partially_refunded";
+type ReviewStatus = "pending" | "approved" | "rejected";
+type TicketStatus = "open" | "in_progress" | "resolved" | "closed";
+type GenericStatus = "active" | "inactive" | "pending" | "approved" | "rejected" | "success" | "warning" | "danger" | "info";
+type StatusBadgeStatus = OrderStatus | PaymentStatus | ReviewStatus | TicketStatus | GenericStatus;
+interface StatusBadgeProps {
+    status: StatusBadgeStatus;
+    label?: string;
+    className?: string;
+}
+declare function StatusBadge({ status, label, className }: StatusBadgeProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Modal — centered dialog with backdrop, multiple sizes, ESC-to-close, and scroll lock.
+ *
+ * Standalone @mohasinac/ui primitive. No app-specific imports.
+ * Renders via React Portal for correct z-index layering.
+ */
+interface ModalProps {
+    isOpen: boolean;
+    onClose: () => void;
+    title?: string;
+    children: React.ReactNode;
+    size?: "sm" | "md" | "lg" | "xl" | "full";
+    showCloseButton?: boolean;
+    /** Additional classNames for the modal panel */
+    className?: string;
+}
+declare function Modal({ isOpen, onClose, title, children, size, showCloseButton, className, }: ModalProps): React.ReactPortal | null;
+
+/**
+ * Drawer — slide-in panel from left, right, or bottom.
+ *
+ * Standalone @mohasinac/ui primitive. No app-specific imports.
+ * Bottom variant gets `rounded-t-2xl` and can be swipe-dismissed via drag handle.
+ */
+interface DrawerProps {
+    isOpen: boolean;
+    onClose: () => void;
+    title?: string;
+    children: React.ReactNode;
+    footer?: React.ReactNode;
+    side?: "left" | "right" | "bottom";
+    /** Width for left/right drawers. Default: 'md' */
+    size?: "sm" | "md" | "lg" | "full";
+    showCloseButton?: boolean;
+    className?: string;
+}
+declare function Drawer({ isOpen, onClose, title, children, footer, side, size, showCloseButton, className, }: DrawerProps): React.ReactPortal | null;
+
+/**
+ * Select — accessible combobox with label, error state, and disabled support.
+ *
+ * Standalone @mohasinac/ui primitive. No app-specific imports.
+ */
+interface SelectOption<V = string> {
+    label: string;
+    value: V;
+    disabled?: boolean;
+}
+interface SelectProps<V extends string = string> {
+    options: SelectOption<V>[];
+    value?: V;
+    onChange?: (value: V) => void;
+    placeholder?: string;
+    label?: string;
+    error?: string;
+    disabled?: boolean;
+    required?: boolean;
+    className?: string;
+    id?: string;
+}
+declare function Select<V extends string = string>({ options, value, onChange, placeholder, label, error, disabled, required, className, id: externalId, }: SelectProps<V>): react_jsx_runtime.JSX.Element;
+
+/**
+ * StarRating — 0–5 star display/interactive rating.
+ *
+ * Standalone @mohasinac/ui primitive. No app-specific imports.
+ * Use `readOnly` for display, omit it for interactive mode with hover preview.
+ */
+interface StarRatingProps {
+    value?: number;
+    onChange?: (value: number) => void;
+    max?: number;
+    size?: "sm" | "md" | "lg";
+    readOnly?: boolean;
+    className?: string;
+    /** Accessible label describing what is being rated */
+    label?: string;
+}
+declare function StarRating({ value, onChange, max, size, readOnly, className, label, }: StarRatingProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Breadcrumb — accessible navigation trail with ChevronRight separators.
+ *
+ * Standalone @mohasinac/ui primitive. No app-specific imports.
+ * Last item is displayed with `font-medium` (non-link, current page).
+ */
+interface BreadcrumbItem {
+    label: string;
+    href?: string;
+}
+interface BreadcrumbProps {
+    items: BreadcrumbItem[];
+    className?: string;
+}
+declare function Breadcrumb({ items, className }: BreadcrumbProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * ImageLightbox — full-screen image overlay with keyboard navigation.
+ *
+ * Standalone @mohasinac/ui primitive. No app-specific imports.
+ * Navigation: ← / → arrow keys, Esc to close. Displays item counter.
+ *
+ * Uses a standard <img> tag for framework portability.
+ * In a Next.js app, callers may swap src with a blurDataURL if desired.
+ */
+interface LightboxImage {
+    src: string;
+    alt?: string;
+    caption?: string;
+}
+interface ImageLightboxProps {
+    images: LightboxImage[];
+    /** The index to open. Pass `null` or `-1` to close. */
+    activeIndex: number | null;
+    onClose: () => void;
+    onNavigate?: (index: number) => void;
+}
+declare function ImageLightbox({ images, activeIndex, onClose, onNavigate, }: ImageLightboxProps): React.ReactPortal | null;
+
+/**
+ * Layout Primitives — Container, Stack, Row, Grid
+ *
+ * Thin component wrappers that turn semantic prop names into the correct
+ * Tailwind class strings from the app's THEME_CONSTANTS token map.
+ * Eliminates repeated inline class strings like "grid grid-cols-1 sm:grid-cols-2
+ * lg:grid-cols-3 gap-4" and "flex flex-row items-center justify-between gap-2".
+ *
+ * Token maps are inlined here (like UI_THEME in Typography.tsx) so the package
+ * stays independent of the host app's @/constants import path.
+ *
+ * @example
+ * ```tsx
+ * // Before
+ * <div className="max-w-7xl mx-auto px-4 sm:px-6 lg:px-8">
+ * <div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">
+ * <div className="flex flex-row items-center justify-between gap-2">
+ * <div className="flex flex-col gap-4">
+ *
+ * // After
+ * <Container>
+ * <Grid cols={3} gap="md">
+ * <Row justify="between" gap="sm">
+ * <Stack gap="md">
+ * ```
+ */
+/**
+ * Gap tokens — maps to `gap-*` Tailwind classes.
+ * Mirrors THEME_CONSTANTS.spacing.gap in the host app.
+ */
+declare const GAP_MAP: {
+    readonly none: "";
+    readonly px: "gap-px";
+    readonly xs: "gap-1";
+    readonly sm: "gap-2";
+    readonly "2.5": "gap-2.5";
+    readonly "3": "gap-3";
+    readonly md: "gap-4";
+    readonly lg: "gap-6";
+    readonly xl: "gap-8";
+    readonly "2xl": "gap-12";
+};
+type GapKey = keyof typeof GAP_MAP;
+/**
+ * Page container sizes.
+ * Mirrors THEME_CONSTANTS.page.container in the host app.
+ */
+declare const CONTAINER_MAP: {
+    /** `max-w-3xl` — blog posts, legal / policy pages */
+    readonly sm: "max-w-3xl mx-auto px-4 sm:px-6 lg:px-8";
+    /** `max-w-4xl` — narrow content, contact, about */
+    readonly md: "max-w-4xl mx-auto px-4 sm:px-6 lg:px-8";
+    /** `max-w-5xl` — medium content, checkout, help */
+    readonly lg: "max-w-5xl mx-auto px-4 sm:px-6 lg:px-8";
+    /** `max-w-6xl` — product detail, cart */
+    readonly xl: "max-w-6xl mx-auto px-4 sm:px-6 lg:px-8";
+    /** `max-w-7xl` — main content grids (default) */
+    readonly "2xl": "max-w-7xl mx-auto px-4 sm:px-6 lg:px-8";
+    /** `max-w-screen-2xl` — full-bleed wide content */
+    readonly full: "max-w-screen-2xl mx-auto px-4 sm:px-6 lg:px-8";
+    /** `max-w-screen-2xl` — wide store/seller layouts (no lg:px-8) */
+    readonly wide: "max-w-screen-2xl mx-auto px-4 sm:px-6";
+};
+type ContainerSize = keyof typeof CONTAINER_MAP;
+/**
+ * Responsive grid column presets.
+ * Mirrors THEME_CONSTANTS.grid in the host app.
+ */
+declare const GRID_MAP: {
+    readonly 1: "grid grid-cols-1";
+    readonly 2: "grid grid-cols-1 sm:grid-cols-2";
+    readonly 3: "grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-3 2xl:grid-cols-3";
+    readonly 4: "grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 xl:grid-cols-4 2xl:grid-cols-4";
+    readonly 5: "grid grid-cols-1 sm:grid-cols-2 md:grid-cols-3 xl:grid-cols-4 2xl:grid-cols-5";
+    readonly 6: "grid grid-cols-2 sm:grid-cols-3 md:grid-cols-4 xl:grid-cols-5 2xl:grid-cols-6";
+    /** Card grid — starts at 2 on mobile, max 5 on 2xl */
+    readonly cards: "grid grid-cols-2 md:grid-cols-3 lg:grid-cols-4 xl:grid-cols-4 2xl:grid-cols-5";
+    /** Equal halves on md+ */
+    readonly halves: "grid grid-cols-1 md:grid-cols-2 xl:grid-cols-2 2xl:grid-cols-2";
+    /** 2fr / 1fr split on md+ */
+    readonly twoThird: "grid grid-cols-1 md:grid-cols-[2fr_1fr]";
+    /** 1fr / 2fr split on md+ */
+    readonly oneThird: "grid grid-cols-1 md:grid-cols-[1fr_2fr]";
+    /** Fixed 280px left sidebar + 1fr on lg+ */
+    readonly sidebar: "grid grid-cols-1 lg:grid-cols-[280px_1fr]";
+    /** 1fr + fixed 280px right sidebar on lg+ */
+    readonly sidebarRight: "grid grid-cols-1 lg:grid-cols-[1fr_280px]";
+    /** Fixed 320px left sidebar + 1fr on lg+ (admin layout) */
+    readonly sidebarWide: "grid grid-cols-1 lg:grid-cols-[320px_1fr]";
+    /** CSS auto-fill, min 200px columns */
+    readonly autoSm: "grid grid-cols-[repeat(auto-fill,minmax(200px,1fr))]";
+    /** CSS auto-fill, min 280px columns */
+    readonly autoMd: "grid grid-cols-[repeat(auto-fill,minmax(280px,1fr))]";
+    /** CSS auto-fill, min 360px columns */
+    readonly autoLg: "grid grid-cols-[repeat(auto-fill,minmax(360px,1fr))]";
+};
+type GridCols = keyof typeof GRID_MAP;
+declare const ITEMS_MAP: {
+    readonly start: "items-start";
+    readonly center: "items-center";
+    readonly end: "items-end";
+    readonly stretch: "items-stretch";
+    readonly baseline: "items-baseline";
+};
+type ItemsAlign = keyof typeof ITEMS_MAP;
+declare const JUSTIFY_MAP: {
+    readonly start: "justify-start";
+    readonly center: "justify-center";
+    readonly end: "justify-end";
+    readonly between: "justify-between";
+    readonly around: "justify-around";
+    readonly evenly: "justify-evenly";
+};
+type JustifyContent = keyof typeof JUSTIFY_MAP;
+/**
+ * Page-level container with max-width + centering + responsive horizontal padding.
+ * Replaces repeated `max-w-7xl mx-auto px-4 sm:px-6 lg:px-8` strings.
+ *
+ * @example
+ * ```tsx
+ * <Container>...</Container>                   // max-w-7xl (default)
+ * <Container size="lg">...</Container>         // max-w-5xl
+ * <Container size="full" as="main">...</Container>
+ * ```
+ */
+interface ContainerProps extends React.HTMLAttributes<HTMLElement> {
+    /**
+     * Max-width breakpoint preset.
+     * - `sm`  → `max-w-3xl`  (blog / policy)
+     * - `md`  → `max-w-4xl`  (contact / about)
+     * - `lg`  → `max-w-5xl`  (checkout / help)
+     * - `xl`  → `max-w-6xl`  (product detail / cart)
+     * - `2xl` → `max-w-7xl`  (main content grids — **default**)
+     * - `full`→ `max-w-screen-2xl` (full-bleed)
+     * - `wide`→ `max-w-screen-2xl` (compact px, no lg step)
+     */
+    size?: ContainerSize;
+    /** Render as a different element (e.g. `"main"`, `"section"`). Defaults to `"div"`. */
+    as?: React.ElementType;
+    children?: React.ReactNode;
+}
+declare function Container({ size, as, className, children, ...props }: ContainerProps): react_jsx_runtime.JSX.Element;
+/**
+ * Vertical flex column. Use instead of `<div className="flex flex-col gap-4">`.
+ *
+ * @example
+ * ```tsx
+ * <Stack gap="sm">
+ *   <Text>Line one</Text>
+ *   <Text>Line two</Text>
+ * </Stack>
+ *
+ * // As a list
+ * <Stack as="ul" gap="xs">
+ *   <Li>Item</Li>
+ * </Stack>
+ * ```
+ */
+interface StackProps extends React.HTMLAttributes<HTMLElement> {
+    /** Space between children. Defaults to `"md"` (`gap-4`). */
+    gap?: GapKey;
+    /** Cross-axis (horizontal) alignment. Defaults to `"stretch"`. */
+    align?: Extract<ItemsAlign, "start" | "center" | "end" | "stretch">;
+    /** Render as a different element. Defaults to `"div"`. */
+    as?: React.ElementType;
+    children?: React.ReactNode;
+}
+declare function Stack({ gap, align, as, className, children, ...props }: StackProps): react_jsx_runtime.JSX.Element;
+/**
+ * Horizontal flex row. Use instead of `<div className="flex items-center gap-3">`.
+ *
+ * @example
+ * ```tsx
+ * <Row gap="sm" justify="between">
+ *   <Heading level={3}>Title</Heading>
+ *   <Button>Action</Button>
+ * </Row>
+ *
+ * <Row gap="xs" wrap>
+ *   <Badge>tag</Badge>
+ *   <Badge>other</Badge>
+ * </Row>
+ * ```
+ */
+interface RowProps extends React.HTMLAttributes<HTMLElement> {
+    /** Space between children. Defaults to `"md"` (`gap-4`). */
+    gap?: GapKey;
+    /** Cross-axis (vertical) alignment. Defaults to `"center"`. */
+    align?: ItemsAlign;
+    /** Main-axis (horizontal) distribution. Defaults to `"start"`. */
+    justify?: JustifyContent;
+    /** Allow children to wrap onto multiple lines. */
+    wrap?: boolean;
+    /** Render as a different element. Defaults to `"div"`. */
+    as?: React.ElementType;
+    children?: React.ReactNode;
+}
+declare function Row({ gap, align, justify, wrap, as, className, children, ...props }: RowProps): react_jsx_runtime.JSX.Element;
+/**
+ * Responsive CSS grid. Use instead of `<div className="grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4">`.
+ *
+ * @example
+ * ```tsx
+ * <Grid cols={3} gap="md">
+ *   <ProductCard />
+ *   <ProductCard />
+ * </Grid>
+ *
+ * <Grid cols="sidebar" gap="lg">
+ *   <Aside>Filters</Aside>
+ *   <Main>Results</Main>
+ * </Grid>
+ * ```
+ */
+interface GridProps extends React.HTMLAttributes<HTMLElement> {
+    /**
+     * Column preset.
+     * - Numbers `1`–`6` → mobile-first responsive stacks
+     * - `"halves"` → equal 2-col on md+
+     * - `"sidebar"` / `"sidebarRight"` / `"sidebarWide"` → fixed+flexible splits
+     * - `"twoThird"` / `"oneThird"` → 2fr/1fr splits
+     * - `"autoSm"` / `"autoMd"` / `"autoLg"` → CSS auto-fill grids
+     * - Omit (or `undefined`) to use a raw `grid` base and supply columns via
+     *   the `className` prop directly (e.g. `className="grid-cols-2"`). Useful
+     *   for fixed non-responsive column counts (form field pairs, button rows).
+     */
+    cols?: GridCols;
+    /** Space between grid cells. Defaults to `"md"` (`gap-4`). */
+    gap?: GapKey;
+    /** Render as a different element. Defaults to `"div"`. */
+    as?: React.ElementType;
+    children?: React.ReactNode;
+}
+declare function Grid({ cols, gap, as, className, children, ...props }: GridProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * DataTable — generic sortable + paginated table promoted to @mohasinac/ui.
+ *
+ * Accepts `tableConfig` and `paginationConfig` for composable configuration.
+ * Apps can spread-merge DEFAULT_TABLE_CONFIG / DEFAULT_PAGINATION_CONFIG and
+ * override only the values they need, then pass the result once.
+ *
+ * Individual flat props (pageSize, stickyHeader, striped, …) still work and
+ * take precedence over anything in tableConfig when explicitly provided.
+ */
+type ViewMode = "table" | "grid" | "list";
+/**
+ * Column descriptor for the DataTable component.
+ * Narrows `render` to return `ReactNode` (TableColumn uses `unknown` so
+ * contracts stays React-free). Fully compatible with `TableColumn<T>`.
+ */
+type DataTableColumn<T> = Omit<TableColumn<T>, "render"> & {
+    render?: (item: T) => ReactNode;
+};
+interface DataTableProps<T> {
+    data: T[];
+    columns: DataTableColumn<T>[];
+    keyExtractor: (item: T) => string;
+    onRowClick?: (item: T) => void;
+    loading?: boolean;
+    emptyMessage?: string;
+    actions?: (item: T) => ReactNode;
+    /** When true, disables internal pagination — render your own externally. Default: false */
+    externalPagination?: boolean;
+    /**
+     * Composable table configuration.
+     * Deep-merged with DEFAULT_TABLE_CONFIG. Individual flat props (pageSize,
+     * stickyHeader, etc.) override this when explicitly provided.
+     */
+    tableConfig?: Partial<TableConfig>;
+    /**
+     * Composable pagination configuration.
+     * Merged with DEFAULT_PAGINATION_CONFIG. Individual flat props override this.
+     */
+    paginationConfig?: Partial<PaginationConfig>;
+    /** Items per page. Explicit value overrides tableConfig.pageSize. Default: 20 */
+    pageSize?: number;
+    mobileCardRender?: (item: T) => ReactNode;
+    emptyState?: ReactNode;
+    emptyIcon?: ReactNode;
+    emptyTitle?: string;
+    stickyHeader?: boolean;
+    striped?: boolean;
+    showViewToggle?: boolean;
+    showTableView?: boolean;
+    viewMode?: ViewMode;
+    defaultViewMode?: ViewMode;
+    onViewModeChange?: (mode: ViewMode) => void;
+    selectable?: boolean;
+    selectedIds?: string[];
+    onSelectionChange?: (ids: string[]) => void;
+    /**
+     * Number of grid columns for card grid view.
+     * Matches Layout GRID_MAP keys: 1–6, "autoSm", "autoMd", "autoLg".
+     * Default: 6 (2→3→4→5→6 across breakpoints).
+     */
+    gridCols?: GridCols;
+    labels?: {
+        loading?: string;
+        noDataTitle?: string;
+        noDataDescription?: string;
+        actions?: string;
+        tableView?: string;
+        gridView?: string;
+        listView?: string;
+    };
+}
+declare function DataTable<T extends Record<string, any>>({ data, columns, keyExtractor, onRowClick, loading, emptyMessage, actions, mobileCardRender, emptyState, emptyIcon, emptyTitle, tableConfig, paginationConfig, externalPagination, pageSize: pageSizeProp, stickyHeader: stickyHeaderProp, striped: stripedProp, showViewToggle: showViewToggleProp, showTableView, viewMode: controlledViewMode, defaultViewMode: defaultViewModeProp, onViewModeChange, selectable: selectableProp, selectedIds, onSelectionChange, gridCols, labels, }: DataTableProps<T>): react_jsx_runtime.JSX.Element;
+
+export { Alert, type AlertProps, Article, type ArticleProps, Aside, type AsideProps, Badge, type BadgeProps, type BadgeVariant, BlockFooter, type BlockFooterProps, BlockHeader, type BlockHeaderProps, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Button, type ButtonProps, Caption, Container, type ContainerProps, type ContainerSize, DataTable, type DataTableColumn, type DataTableProps, Divider, type DividerProps, Drawer, type DrawerProps, GRID_MAP, type GapKey, type GenericStatus, Grid, type GridCols, type GridProps, Heading, ImageLightbox, type ImageLightboxProps, IndeterminateProgress, type IndeterminateProgressProps, Label, Li, type LiProps, type LightboxImage, Main, type MainProps, Modal, type ModalProps, Nav, type NavProps, Ol, type OlProps, type OrderStatus, Pagination, type PaginationProps, type PaymentStatus, Progress, type ProgressProps, type ReviewStatus, Row, type RowProps, Section, type SectionProps, Select, type SelectOption, type SelectProps, Skeleton, type SkeletonProps, Span, Spinner, type SpinnerProps, Stack, type StackProps, StarRating, type StarRatingProps, StatusBadge, type StatusBadgeProps, type StatusBadgeStatus, Text, type TicketStatus, Ul, type UlProps };