@almadar/ui 2.15.7 → 2.15.10

package/dist/docs/index.d.cts

@@ -0,0 +1,412 @@
+import React from 'react';
+import { LucideIcon } from 'lucide-react';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+/**
+ * Box Component
+ *
+ * A versatile layout primitive that provides spacing, background, border, and shadow controls.
+ * Think of it as a styled div with consistent design tokens.
+ */
+
+type BoxPadding = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
+type BoxMargin = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "auto";
+type BoxBg = "transparent" | "primary" | "secondary" | "muted" | "accent" | "surface" | "overlay";
+type BoxRounded = "none" | "sm" | "md" | "lg" | "xl" | "2xl" | "full";
+type BoxShadow = "none" | "sm" | "md" | "lg" | "xl";
+interface BoxProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Padding on all sides */
+    padding?: BoxPadding;
+    /** Horizontal padding (overrides padding for x-axis) */
+    paddingX?: BoxPadding;
+    /** Vertical padding (overrides padding for y-axis) */
+    paddingY?: BoxPadding;
+    /** Margin on all sides */
+    margin?: BoxMargin;
+    /** Horizontal margin */
+    marginX?: BoxMargin;
+    /** Vertical margin */
+    marginY?: BoxMargin;
+    /** Background color */
+    bg?: BoxBg;
+    /** Show border */
+    border?: boolean;
+    /** Border radius */
+    rounded?: BoxRounded;
+    /** Box shadow */
+    shadow?: BoxShadow;
+    /** Display type */
+    display?: "block" | "inline" | "inline-block" | "flex" | "inline-flex" | "grid";
+    /** Fill available width */
+    fullWidth?: boolean;
+    /** Fill available height */
+    fullHeight?: boolean;
+    /** Overflow behavior */
+    overflow?: "auto" | "hidden" | "visible" | "scroll";
+    /** Position */
+    position?: "relative" | "absolute" | "fixed" | "sticky";
+    /** HTML element to render as */
+    as?: React.ElementType;
+    /** Declarative event name — emits UI:{action} via eventBus on click */
+    action?: string;
+    /** Payload to include with the action event */
+    actionPayload?: Record<string, unknown>;
+    /** Declarative hover event — emits UI:{hoverEvent} with { hovered: true/false } on mouseEnter/mouseLeave */
+    hoverEvent?: string;
+}
+/**
+ * Box - Versatile container component with design tokens
+ */
+declare const Box: React.ForwardRefExoticComponent<BoxProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Stack Component
+ *
+ * A layout primitive for arranging children in a vertical or horizontal stack with consistent spacing.
+ * Includes convenience exports VStack and HStack for common use cases.
+ */
+
+type StackDirection = "horizontal" | "vertical";
+type StackGap = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
+type StackAlign = "start" | "center" | "end" | "stretch" | "baseline";
+type StackJustify = "start" | "center" | "end" | "between" | "around" | "evenly";
+interface StackProps {
+    /** Stack direction */
+    direction?: StackDirection;
+    /** Gap between children */
+    gap?: StackGap;
+    /** Align items on the cross axis */
+    align?: StackAlign;
+    /** Justify items on the main axis */
+    justify?: StackJustify;
+    /** Allow items to wrap */
+    wrap?: boolean;
+    /** Reverse the order of children */
+    reverse?: boolean;
+    /** Fill available space (flex: 1) */
+    flex?: boolean;
+    /** Custom class name */
+    className?: string;
+    /** Inline styles */
+    style?: React.CSSProperties;
+    /** Children elements */
+    children?: React.ReactNode;
+    /** HTML element to render as */
+    as?: React.ElementType;
+    /** Click handler */
+    onClick?: (e: React.MouseEvent) => void;
+    /** Keyboard handler */
+    onKeyDown?: (e: React.KeyboardEvent) => void;
+    /** Role for accessibility */
+    role?: string;
+    /** Tab index for focus management */
+    tabIndex?: number;
+    /** Declarative event name — emits UI:{action} via eventBus on click */
+    action?: string;
+    /** Payload to include with the action event */
+    actionPayload?: Record<string, unknown>;
+    /** When true, horizontal stacks flip to vertical below the md breakpoint (768px) */
+    responsive?: boolean;
+}
+/**
+ * VStack - Vertical stack shorthand
+ */
+interface VStackProps extends Omit<StackProps, "direction"> {
+}
+declare const VStack: React.FC<VStackProps>;
+/**
+ * HStack - Horizontal stack shorthand
+ */
+interface HStackProps extends Omit<StackProps, "direction"> {
+}
+declare const HStack: React.FC<HStackProps>;
+
+/**
+ * Typography Atom Component
+ *
+ * Text elements following the KFlow design system with theme-aware styling.
+ */
+
+type TypographyVariant = "h1" | "h2" | "h3" | "h4" | "h5" | "h6" | "heading" | "subheading" | "body1" | "body2" | "body" | "caption" | "overline" | "small" | "large" | "label";
+type TypographySize = "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";
+interface TypographyProps {
+    /** Typography variant */
+    variant?: TypographyVariant;
+    /** Heading level (1-6) - alternative to variant for headings */
+    level?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Text color */
+    color?: "primary" | "secondary" | "muted" | "error" | "success" | "warning" | "inherit";
+    /** Text alignment */
+    align?: "left" | "center" | "right";
+    /** Font weight override */
+    weight?: "light" | "normal" | "medium" | "semibold" | "bold";
+    /** Font size override */
+    size?: TypographySize;
+    /** Truncate with ellipsis (single line) */
+    truncate?: boolean;
+    /** Overflow handling mode */
+    overflow?: "visible" | "hidden" | "wrap" | "clamp-2" | "clamp-3";
+    /** Custom HTML element */
+    as?: keyof React.JSX.IntrinsicElements;
+    /** HTML id attribute */
+    id?: string;
+    /** Additional class names */
+    className?: string;
+    /** Inline style */
+    style?: React.CSSProperties;
+    /** Text content (alternative to children) */
+    content?: React.ReactNode;
+    /** Children elements */
+    children?: React.ReactNode;
+}
+declare const Typography: React.FC<TypographyProps>;
+
+type ButtonVariant = "primary" | "secondary" | "ghost" | "danger" | "success" | "warning" | "default";
+type ButtonSize = "sm" | "md" | "lg";
+interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+    isLoading?: boolean;
+    /** Left icon as ReactNode, Lucide component, or string name (e.g. "plus", "trash") */
+    leftIcon?: React.ReactNode | LucideIcon | string;
+    /** Right icon as ReactNode, Lucide component, or string name */
+    rightIcon?: React.ReactNode | LucideIcon | string;
+    /** Alias for leftIcon */
+    icon?: React.ReactNode | LucideIcon | string;
+    /** Alias for rightIcon */
+    iconRight?: React.ReactNode | LucideIcon | string;
+    /** Declarative event name — emits UI:{action} via eventBus on click */
+    action?: string;
+    /** Payload to include with the action event */
+    actionPayload?: Record<string, unknown>;
+    /** Button label text (alternative to children for schema-driven rendering) */
+    label?: string;
+}
+declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
+
+/**
+ * Icon Atom Component
+ *
+ * A wrapper component for Lucide icons with consistent sizing and styling.
+ * Uses theme-aware CSS variables for stroke width and color.
+ *
+ * Supports two APIs:
+ * - `icon` prop: Pass a LucideIcon component directly
+ * - `name` prop: Pass a string icon name (resolved from iconMap)
+ */
+
+type IconSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+type IconAnimation = 'spin' | 'pulse' | 'none';
+interface IconProps {
+    /** Lucide icon component (preferred for type-safe usage) */
+    icon?: LucideIcon;
+    /** Icon name as string (resolved from iconMap) */
+    name?: string;
+    /** Size of the icon */
+    size?: IconSize;
+    /** Color class (Tailwind color class) or 'inherit' for theme default */
+    color?: string;
+    /** Animation type */
+    animation?: IconAnimation;
+    /** Additional CSS classes */
+    className?: string;
+    /** Icon stroke width - uses theme default if not specified */
+    strokeWidth?: number;
+    /** Inline style */
+    style?: React.CSSProperties;
+}
+declare const Icon: React.FC<IconProps>;
+
+type CardShadow = "none" | "sm" | "md" | "lg";
+interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
+    variant?: "default" | "bordered" | "elevated" | "interactive";
+    padding?: "none" | "sm" | "md" | "lg";
+    /** Card title - renders in header if provided */
+    title?: string;
+    /** Card subtitle - renders below title */
+    subtitle?: string;
+    /** Shadow size override */
+    shadow?: CardShadow;
+}
+declare const Card: React.ForwardRefExoticComponent<CardProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * Divider Atom Component
+ *
+ * A divider component for separating content sections.
+ */
+
+type DividerOrientation = "horizontal" | "vertical";
+type DividerVariant = "solid" | "dashed" | "dotted";
+interface DividerProps {
+    /**
+     * Orientation of the divider
+     * @default 'horizontal'
+     */
+    orientation?: DividerOrientation;
+    /**
+     * Text label to display in the divider
+     */
+    label?: string;
+    /**
+     * Line style variant
+     * @default 'solid'
+     */
+    variant?: DividerVariant;
+    /**
+     * Additional CSS classes
+     */
+    className?: string;
+}
+declare const Divider: React.FC<DividerProps>;
+
+interface SelectOption {
+    value: string;
+    label: string;
+}
+interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, "onChange"> {
+    /** Placeholder text */
+    placeholder?: string;
+    /** Current value */
+    value?: string | number;
+    /** Whether input is disabled */
+    disabled?: boolean;
+    /** Declarative event name for trait dispatch */
+    action?: string;
+    /** Input type - supports 'select' and 'textarea' in addition to standard types */
+    inputType?: "text" | "email" | "password" | "number" | "tel" | "url" | "search" | "date" | "datetime-local" | "time" | "checkbox" | "select" | "textarea";
+    error?: string;
+    leftIcon?: React.ReactNode;
+    rightIcon?: React.ReactNode;
+    /** Lucide icon component for left side (convenience prop) */
+    icon?: LucideIcon;
+    /** Show clear button when input has value */
+    clearable?: boolean;
+    /** Callback when clear button is clicked */
+    onClear?: () => void;
+    /** Options for select type */
+    options?: SelectOption[];
+    /** Rows for textarea type */
+    rows?: number;
+    /** onChange handler - accepts events from input, select, or textarea */
+    onChange?: React.ChangeEventHandler<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement>;
+}
+declare const Input: React.ForwardRefExoticComponent<InputProps & React.RefAttributes<HTMLInputElement | HTMLSelectElement | HTMLTextAreaElement>>;
+
+/**
+ * DocSidebar Molecule Component
+ *
+ * A documentation navigation sidebar with collapsible category sections.
+ * Composes from Box, VStack, HStack, Typography, and Icon atoms.
+ */
+
+interface DocSidebarItem {
+    /** Display label */
+    label: string;
+    /** Navigation href */
+    href?: string;
+    /** Nested child items (makes this a collapsible category) */
+    items?: DocSidebarItem[];
+    /** Whether this item is currently active */
+    active?: boolean;
+}
+interface DocSidebarProps {
+    /** Sidebar navigation items */
+    items: DocSidebarItem[];
+    /** Additional CSS classes */
+    className?: string;
+}
+declare const DocSidebar: React.FC<DocSidebarProps>;
+
+/**
+ * DocTOC Molecule Component
+ *
+ * A table of contents component with active section highlighting.
+ * Composes from Box, VStack, and Typography atoms.
+ */
+
+interface DocTOCItem {
+    /** Heading element id to link to */
+    id: string;
+    /** Display label */
+    label: string;
+    /** Heading level: 2 for h2, 3 for h3, etc. */
+    level: number;
+}
+interface DocTOCProps {
+    /** Table of contents items */
+    items: DocTOCItem[];
+    /** Currently active section id */
+    activeId?: string;
+    /** Additional CSS classes */
+    className?: string;
+}
+declare const DocTOC: React.FC<DocTOCProps>;
+
+/**
+ * DocBreadcrumb Molecule Component
+ *
+ * A breadcrumb navigation component for documentation pages.
+ * Composes from HStack, Typography, and Icon atoms.
+ */
+
+interface DocBreadcrumbItem {
+    /** Display label */
+    label: string;
+    /** Navigation href (omit for the current/last item) */
+    href?: string;
+}
+interface DocBreadcrumbProps {
+    /** Breadcrumb path items, last item is treated as current page */
+    items: DocBreadcrumbItem[];
+    /** Additional CSS classes */
+    className?: string;
+}
+declare const DocBreadcrumb: React.FC<DocBreadcrumbProps>;
+
+interface DocCodeBlockProps {
+    /** Code content to display */
+    code: string;
+    /** Programming language label */
+    language?: string;
+    /** Optional title/filename shown in the header bar */
+    title?: string;
+    /** Show line numbers in the gutter */
+    showLineNumbers?: boolean;
+    /** Additional class names */
+    className?: string;
+}
+declare function DocCodeBlock({ code, language, title, showLineNumbers, className, }: DocCodeBlockProps): react_jsx_runtime.JSX.Element;
+
+interface DocPaginationLink {
+    label: string;
+    href: string;
+    category?: string;
+}
+interface DocPaginationProps {
+    /** Previous page link */
+    prev?: DocPaginationLink;
+    /** Next page link */
+    next?: DocPaginationLink;
+    /** Additional class names */
+    className?: string;
+}
+declare function DocPagination({ prev, next, className }: DocPaginationProps): react_jsx_runtime.JSX.Element | null;
+
+interface DocSearchResult {
+    title: string;
+    href: string;
+    excerpt?: string;
+    category?: string;
+}
+interface DocSearchProps {
+    /** Placeholder text for the input */
+    placeholder?: string;
+    /** Callback invoked with the search query, returns results */
+    onSearch?: (query: string) => DocSearchResult[] | Promise<DocSearchResult[]>;
+    /** Additional class names */
+    className?: string;
+}
+declare function DocSearch({ placeholder, onSearch, className, }: DocSearchProps): react_jsx_runtime.JSX.Element;
+
+export { Box, Button, Card, Divider, DocBreadcrumb, type DocBreadcrumbItem, type DocBreadcrumbProps, DocCodeBlock, type DocCodeBlockProps, DocPagination, type DocPaginationProps, DocSearch, type DocSearchProps, type DocSearchResult, DocSidebar, type DocSidebarItem, type DocSidebarProps, DocTOC, type DocTOCItem, type DocTOCProps, HStack, Icon, Input, Typography, VStack };

package/dist/docs/index.d.ts

@@ -0,0 +1,29 @@
+/**
+ * @almadar/ui/docs
+ *
+ * SSR-safe subset of @almadar/ui for documentation sites.
+ * Contains doc-specific molecules composed from @almadar/ui atoms.
+ * Designed to eventually replace Docusaurus's built-in doc components.
+ *
+ * Atoms are re-exported from @almadar/ui/marketing for convenience.
+ */
+export { Box } from '../components/atoms/Box';
+export { VStack, HStack } from '../components/atoms/Stack';
+export { Typography } from '../components/atoms/Typography';
+export { Button } from '../components/atoms/Button';
+export { Icon } from '../components/atoms/Icon';
+export { Card } from '../components/atoms/Card';
+export { Divider } from '../components/atoms/Divider';
+export { Input } from '../components/atoms/Input';
+export { DocSidebar } from '../components/molecules/DocSidebar';
+export type { DocSidebarProps, DocSidebarItem } from '../components/molecules/DocSidebar';
+export { DocTOC } from '../components/molecules/DocTOC';
+export type { DocTOCProps, DocTOCItem } from '../components/molecules/DocTOC';
+export { DocBreadcrumb } from '../components/molecules/DocBreadcrumb';
+export type { DocBreadcrumbProps, DocBreadcrumbItem } from '../components/molecules/DocBreadcrumb';
+export { DocCodeBlock } from '../components/molecules/DocCodeBlock';
+export type { DocCodeBlockProps } from '../components/molecules/DocCodeBlock';
+export { DocPagination } from '../components/molecules/DocPagination';
+export type { DocPaginationProps } from '../components/molecules/DocPagination';
+export { DocSearch } from '../components/molecules/DocSearch';
+export type { DocSearchProps, DocSearchResult } from '../components/molecules/DocSearch';