@almadar/ui 5.125.0 → 5.126.0

package/dist/marketing/index.d.ts

@@ -0,0 +1,1086 @@
+import React from 'react';
+import { EventKey, EventPayload, AssetUrl, Asset } from '@almadar/core';
+import { LucideIcon } from 'lucide-react';
+
+/**
+ * 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> {
+    /** Additional CSS classes applied to the root element. */
+    className?: string;
+    /** Data-theme attribute applied to the root element for CSS theme scoping (e.g. almadar-website-dark). */
+    'data-theme'?: string;
+    /** 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?: EventKey;
+    /** Payload to include with the action event */
+    actionPayload?: EventPayload;
+    /** Declarative hover event — emits UI:{hoverEvent} with { hovered: true/false } on mouseEnter/mouseLeave */
+    hoverEvent?: EventKey;
+    /** When true (default), a touch/pen tap also fires `hoverEvent` (toggling hovered) so hover-only reveals work on touch. */
+    tapReveal?: boolean;
+    /** Maximum width (CSS value, e.g., "550px", "80rem") */
+    maxWidth?: string;
+    /** Children elements */
+    children?: React.ReactNode;
+}
+/**
+ * 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?: EventKey;
+    /** Payload to include with the action event */
+    actionPayload?: EventPayload;
+    /** 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";
+/** `none` = no size override — the variant's baked size applies. */
+type TypographySize = "none" | "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 — `none` = no override, the variant's baked weight applies */
+    weight?: "none" | "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>;
+
+/**
+ * Cross-cutting atom-level prop shapes shared across the design system.
+ */
+
+/**
+ * Canonical semantic color palette.  Values are the Tailwind / CSS-var token
+ * names that every component in the design system understands.  Prefer this
+ * over a bare `string` for any `color` or `variant` prop.
+ */
+type ColorToken = 'primary' | 'secondary' | 'success' | 'warning' | 'error' | 'muted';
+/**
+ * A labelled link/CTA used by marketing molecules (HeroSection, CTABanner,
+ * PricingCard) for their primary/secondary call-to-action props.
+ */
+type LinkAction = {
+    label: string;
+    href: string;
+};
+/** An image with its required alt text. */
+type ImageSource = {
+    src: AssetUrl;
+    alt: string;
+};
+
+/**
+ * Icon Atom Component
+ *
+ * Renders an icon from the active icon family (Layer 1 Iconography axis —
+ * see lib/iconFamily.ts). Canonical names are lucide kebab-case; the resolver
+ * dispatches to phosphor / tabler / fa-solid when `--icon-family` selects them,
+ * re-rendering automatically on theme switch.
+ *
+ * Supports two APIs:
+ * - `icon` prop: Pass a LucideIcon component directly (bypasses family resolver
+ *   — used for direct lucide component refs, stays in lucide regardless of theme)
+ * - `name` prop: Pass a canonical kebab-case name (family-aware, swaps on theme)
+ */
+
+type IconSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+type IconAnimation = 'spin' | 'pulse' | 'none';
+
+/**
+ * Canonical icon-input type: a Lucide component reference OR a canonical
+ * kebab-case icon name string. The single source of truth for every
+ * icon-bearing prop across `@almadar/ui` — pattern-sync's parser maps this
+ * union to the `icon` config type, so the factory inspector renders an
+ * IconPicker and a string name resolves via `resolveIcon`. Never declare an
+ * icon prop as `React.ReactNode` (it collapses to a non-editable `node`).
+ */
+type IconInput = LucideIcon | string;
+interface IconProps {
+    /**
+     * Lucide icon component (preferred for type-safe usage), OR a canonical
+     * kebab-case icon name string — a string is treated exactly like `name` so
+     * trait/factory authors can pass an icon by name through the `icon` prop.
+     */
+    icon?: IconInput;
+    /** Icon name as string (resolved from iconMap) */
+    name?: string;
+    /** Size of the icon */
+    size?: IconSize;
+    /** Semantic palette token or an arbitrary Tailwind color class. */
+    color?: ColorToken | 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 ButtonVariant = "primary" | "secondary" | "ghost" | "danger" | "success" | "warning" | "default";
+type ButtonSize = "sm" | "md" | "lg";
+interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+    /** Additional CSS classes applied to the root element. */
+    className?: string;
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+    isLoading?: boolean;
+    /** Left icon: a Lucide component or a canonical icon name string (e.g. "plus", "trash"). */
+    leftIcon?: IconInput;
+    /** Right icon: a Lucide component or a canonical icon name string. */
+    rightIcon?: IconInput;
+    /** Alias for leftIcon */
+    icon?: IconInput;
+    /** Alias for rightIcon */
+    iconRight?: IconInput;
+    /** Asset image rendered as the leading icon; takes precedence over icon/leftIcon when provided. */
+    iconAsset?: Asset;
+    /** Declarative event name — emits UI:{action} via eventBus on click */
+    action?: EventKey;
+    /** Payload to include with the action event */
+    actionPayload?: EventPayload;
+    /** Button label text (alternative to children for schema-driven rendering) */
+    label?: string;
+    /** Disable the button (greys out, blocks click events) */
+    disabled?: boolean;
+    /** Test identifier for automated tests */
+    'data-testid'?: string;
+}
+declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
+
+type BadgeVariant = "default" | "primary" | "secondary" | "success" | "warning" | "danger" | "error" | "info" | "neutral";
+type BadgeSize = "sm" | "md" | "lg";
+interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
+    /** Additional CSS classes applied to the root element. */
+    className?: string;
+    variant?: BadgeVariant;
+    size?: BadgeSize;
+    /** Numeric count or amount to display in badge */
+    amount?: number;
+    /** Badge label text (alternative to children for schema-driven rendering).
+     *  Numeric values are auto-coerced to string for rendering — common case
+     *  is unread counts, error counts, status codes, etc. */
+    label?: string | number;
+    /** Lucide icon component or canonical kebab-case icon name string */
+    icon?: IconInput;
+    /** Asset image rendered as the badge icon; takes precedence over icon when provided. */
+    iconAsset?: Asset;
+    /** When set, renders a small X button on the right of the badge that
+     *  invokes this handler — turns the badge into a removable chip.
+     *  Used by the TagInput molecule and other "list of removable values"
+     *  surfaces. */
+    onRemove?: () => void;
+    /** Accessible label for the remove button. Defaults to "Remove". */
+    removeLabel?: string;
+}
+declare const Badge: React.ForwardRefExoticComponent<BadgeProps & React.RefAttributes<HTMLSpanElement>>;
+
+type CardShadow = "none" | "sm" | "md" | "lg";
+/**
+ * Layer 2 visual treatment for the card pattern — orthogonal to the semantic
+ * `variant` (which conveys role / state).
+ */
+type CardLook = "elevated" | "flat-bordered" | "borderless-divider" | "ticket" | "invoice" | "chip" | "tile-image-first";
+interface CardProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Additional CSS classes applied to the root element. */
+    className?: string;
+    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;
+    /** Layer 2 visual treatment — orthogonal to the semantic variant. */
+    look?: CardLook;
+    /** Card content */
+    children?: React.ReactNode;
+    /** Declarative event key emitted on click for trait dispatch */
+    action?: EventKey;
+    /** Shows a skeleton/spinner overlay while true. */
+    loading?: boolean;
+}
+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>;
+
+/**
+ * Center Component
+ *
+ * A layout utility that centers its children horizontally and/or vertically.
+ */
+
+interface CenterProps {
+    /** Center inline (width fits content) vs block (full width) */
+    inline?: boolean;
+    /** Center only horizontally */
+    horizontal?: boolean;
+    /** Center only vertically */
+    vertical?: boolean;
+    /** Minimum height (useful for vertical centering) */
+    minHeight?: string | number;
+    /** Fill available height */
+    fullHeight?: boolean;
+    /** Fill available width */
+    fullWidth?: boolean;
+    /** Custom class name */
+    className?: string;
+    /** Inline styles */
+    style?: React.CSSProperties;
+    /** Children elements */
+    children: React.ReactNode;
+    /** HTML element to render as */
+    as?: React.ElementType;
+}
+/**
+ * Center - Centers content horizontally and/or vertically
+ */
+declare const Center: React.FC<CenterProps>;
+
+/**
+ * Spacer Component
+ *
+ * A flexible spacer that expands to fill available space in a flex container.
+ * Useful for pushing elements apart or creating consistent spacing.
+ */
+
+type SpacerSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'auto';
+interface SpacerProps {
+    /** Fixed size (auto = flex grow) */
+    size?: SpacerSize;
+    /** Orientation (for fixed sizes) */
+    axis?: 'horizontal' | 'vertical';
+    /** Custom class name */
+    className?: string;
+}
+/**
+ * Spacer - Flexible spacing element for flex layouts
+ *
+ * Usage:
+ * - size="auto" (default): Expands to fill available space (flex: 1)
+ * - size="md": Fixed size spacing
+ */
+declare const Spacer: React.FC<SpacerProps>;
+
+type ContentSectionBackground = "default" | "alt" | "dark" | "gradient";
+type ContentSectionPadding = "sm" | "md" | "lg";
+interface ContentSectionProps {
+    /** Section content */
+    children: React.ReactNode;
+    /** Background style */
+    background?: ContentSectionBackground;
+    /** Vertical padding size */
+    padding?: ContentSectionPadding;
+    /** HTML id for anchor linking */
+    id?: string;
+    /** Additional class names */
+    className?: string;
+}
+declare const ContentSection: React.ForwardRefExoticComponent<ContentSectionProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * HeroSection Molecule Component
+ *
+ * A full-width hero section for landing pages and marketing content.
+ * Composes atoms: Box, VStack, HStack, Badge, Typography, Button.
+ * Optionally includes an InstallBox molecule for CLI commands.
+ */
+
+interface HeroSectionProps {
+    tag?: string;
+    tagVariant?: 'primary' | 'secondary' | 'accent';
+    title: string;
+    titleAccent?: string;
+    subtitle: string;
+    primaryAction?: LinkAction;
+    secondaryAction?: LinkAction;
+    installCommand?: string;
+    image?: ImageSource;
+    imagePosition?: 'below' | 'right' | 'background';
+    background?: 'dark' | 'gradient' | 'subtle';
+    align?: 'center' | 'left';
+    /** Background element (SVG animation, etc.) rendered behind hero content */
+    backgroundElement?: React.ReactNode;
+    children?: React.ReactNode;
+    className?: string;
+}
+declare const HeroSection: React.FC<HeroSectionProps>;
+
+/**
+ * CTABanner Molecule Component
+ *
+ * A call-to-action banner with title, subtitle, and action buttons.
+ * Uses the site's theme naturally - no forced color inversions.
+ */
+
+type CTABannerBackground = 'default' | 'alt' | 'dark' | 'gradient' | 'primary';
+interface CTABannerProps {
+    /** Banner headline */
+    title: string;
+    /** Supporting text below the title */
+    subtitle?: string;
+    /** Primary action button config */
+    primaryAction?: LinkAction;
+    /** Secondary action button config */
+    secondaryAction?: LinkAction;
+    /** Background style */
+    background?: CTABannerBackground;
+    /** Content alignment */
+    align?: 'center' | 'left';
+    /** Additional class names */
+    className?: string;
+}
+declare const CTABanner: React.FC<CTABannerProps>;
+
+/**
+ * FeatureCard Molecule Component
+ *
+ * A card highlighting a feature with icon, title, description, and optional link.
+ * Composes Card, VStack, Icon, Typography, and Button atoms.
+ */
+
+/**
+ * FeatureCard — an icon-led card pairing a title and description to call out a
+ * single product feature.
+ *
+ * @capabilities feature highlight, benefit callout, product capability card, feature-grid tile
+ */
+interface FeatureCardProps {
+    icon?: IconInput;
+    /** Feature title */
+    title: string;
+    /** Feature description */
+    description: string;
+    /** Optional link URL */
+    href?: string;
+    /** Label for the link button */
+    linkLabel?: string;
+    /** Card visual variant */
+    variant?: 'default' | 'bordered' | 'elevated' | 'interactive';
+    /** Card size affecting icon and spacing */
+    size?: 'sm' | 'md' | 'lg';
+    /** Additional class names */
+    className?: string;
+}
+declare const FeatureCard: React.FC<FeatureCardProps>;
+
+/**
+ * FeatureGrid Molecule Component
+ *
+ * A responsive grid layout for displaying multiple FeatureCards.
+ * Composes SimpleGrid and FeatureCard molecules.
+ */
+
+interface FeatureGridProps {
+    /** Array of feature card configurations */
+    items: FeatureCardProps[];
+    /** Number of grid columns */
+    columns?: 2 | 3 | 4 | 6;
+    /** Gap between grid items */
+    gap?: 'sm' | 'md' | 'lg';
+    /** Additional class names */
+    className?: string;
+}
+declare const FeatureGrid: React.FC<FeatureGridProps>;
+
+/**
+ * PricingCard Molecule Component
+ *
+ * A pricing tier card showing plan name, price, features, and CTA button.
+ * Composes atoms: Card, VStack, HStack, Badge, Typography, Icon, Divider, Spacer, Button.
+ */
+
+/**
+ * PricingCard — a single pricing-tier card with price, billing period, feature
+ * list, and call-to-action.
+ *
+ * @capabilities pricing tier, plan card, subscription tier, plan comparison card, price plan
+ */
+interface PricingCardProps {
+    name: string;
+    price: string;
+    description?: string;
+    features: string[];
+    action: LinkAction;
+    highlighted?: boolean;
+    badge?: string;
+    className?: string;
+}
+declare const PricingCard: React.FC<PricingCardProps>;
+
+/**
+ * PricingGrid Molecule Component
+ *
+ * A responsive grid of PricingCard molecules.
+ * Composes: SimpleGrid + PricingCard.
+ */
+
+interface PricingGridProps {
+    plans: PricingCardProps[];
+    className?: string;
+}
+declare const PricingGrid: React.FC<PricingGridProps>;
+
+/**
+ * SplitSection Molecule Component
+ *
+ * A two-column content section with text on one side and an image (or custom content) on the other.
+ * Composes Box, HStack, VStack, Typography, and Icon atoms.
+ */
+
+interface SplitSectionProps {
+    title: string;
+    description: string | React.ReactNode;
+    bullets?: string[];
+    image?: ImageSource;
+    imagePosition?: 'left' | 'right';
+    background?: 'default' | 'alt';
+    children?: React.ReactNode;
+    className?: string;
+}
+declare const SplitSection: React.FC<SplitSectionProps>;
+
+/**
+ * InstallBox Molecule Component
+ *
+ * A copyable command display box for install/CLI commands.
+ * Shows a monospace command with a copy-to-clipboard button.
+ */
+
+interface InstallBoxProps {
+    /** The command to display and copy */
+    command: string;
+    /** Optional label above the command */
+    label?: string;
+    /** Additional class names */
+    className?: string;
+}
+declare const InstallBox: React.FC<InstallBoxProps>;
+
+/**
+ * StepFlow Molecule Component
+ *
+ * A step-by-step progress indicator supporting horizontal and vertical orientations.
+ * Composes Center, Typography, Icon, HStack, VStack, Box, and Divider atoms.
+ */
+
+interface StepItemProps {
+    number?: number;
+    title: string;
+    description: string;
+    icon?: IconInput;
+}
+interface StepFlowProps {
+    steps: StepItemProps[];
+    orientation?: 'horizontal' | 'vertical';
+    showConnectors?: boolean;
+    className?: string;
+}
+declare const StepFlow: React.FC<StepFlowProps>;
+
+/**
+ * StatsGrid Molecule Component
+ *
+ * A responsive grid of stat items showing value + label pairs.
+ * Composes: SimpleGrid + VStack + Typography.
+ * Uses StatDisplay internally when available for consistent styling.
+ */
+
+interface StatItem {
+    value: string;
+    label: string;
+}
+interface StatsGridProps {
+    stats: StatItem[];
+    columns?: 2 | 3 | 4 | 6;
+    className?: string;
+}
+declare const StatsGrid: React.FC<StatsGridProps>;
+
+/**
+ * TagCloud Molecule Component
+ *
+ * A collection of tags displayed as badges in a wrapping layout.
+ * Composes HStack and Badge atoms.
+ */
+
+interface TagCloudItem {
+    label: string;
+    href?: string;
+    variant?: string;
+}
+interface TagCloudProps {
+    tags: string[] | TagCloudItem[];
+    variant?: 'default' | 'primary' | 'accent';
+    className?: string;
+}
+declare const TagCloud: React.FC<TagCloudProps>;
+
+/**
+ * CommunityLinks Molecule Component
+ *
+ * Displays community platform links (GitHub, Discord, Twitter) as styled buttons.
+ * Composes VStack, HStack, Typography, Button, and Icon atoms.
+ */
+
+interface GithubLink {
+    url: string;
+    stars?: number;
+}
+interface DiscordLink {
+    url: string;
+    members?: number;
+}
+interface TwitterLink {
+    url: string;
+    followers?: number;
+}
+interface CommunityLinksProps {
+    github?: GithubLink;
+    discord?: DiscordLink;
+    twitter?: TwitterLink;
+    heading?: string;
+    subtitle?: string;
+    className?: string;
+}
+declare const CommunityLinks: React.FC<CommunityLinksProps>;
+
+/**
+ * ServiceCatalog Molecule Component
+ *
+ * Displays a grid of services organized by layer, each shown as a card
+ * with a layer badge and service name.
+ */
+
+interface ServiceCatalogItem {
+    name: string;
+    layer: string;
+    layerColor?: string;
+}
+interface ServiceCatalogProps {
+    /** List of services to display */
+    services: ServiceCatalogItem[];
+    /** Additional class names */
+    className?: string;
+}
+declare const ServiceCatalog: React.FC<ServiceCatalogProps>;
+
+/**
+ * ShowcaseCard Molecule Component
+ *
+ * A card for showcasing projects, demos, or portfolio items with an image, badge, and description.
+ * Composes Card, Box, VStack, Badge, and Typography atoms.
+ */
+
+interface ShowcaseCardProps {
+    title: string;
+    description?: string;
+    image: ImageSource;
+    href?: string;
+    badge?: string;
+    accentColor?: string;
+    className?: string;
+}
+declare const ShowcaseCard: React.FC<ShowcaseCardProps>;
+
+/**
+ * TeamCard Molecule Component
+ *
+ * A card displaying a team member with avatar, name, role, and bio.
+ * Composes Card, VStack, Avatar, and Typography atoms.
+ */
+
+interface TeamCardProps {
+    name: string;
+    nameAr?: string;
+    role: string;
+    bio: string;
+    avatar?: AssetUrl | {
+        initials: string;
+    };
+    className?: string;
+}
+declare const TeamCard: React.FC<TeamCardProps>;
+
+/**
+ * CaseStudyCard Molecule Component
+ *
+ * A card for displaying case studies with category badge, title,
+ * description, and a call-to-action link button.
+ */
+
+/**
+ * CaseStudyCard — a card summarizing a customer case study with logo, headline
+ * result, and link.
+ *
+ * @capabilities customer story, success story, client story card, results showcase, proof-point card
+ */
+interface CaseStudyCardProps {
+    /** Case study title */
+    title: string;
+    /** Short description of the case study */
+    description: string;
+    /** Category label shown as a badge */
+    category: string;
+    /** Custom background color for the category badge (CSS value) */
+    categoryColor?: string;
+    /** URL the card links to */
+    href: string;
+    /** Label for the link button */
+    linkLabel?: string;
+    /** Additional class names */
+    className?: string;
+}
+declare const CaseStudyCard: React.FC<CaseStudyCardProps>;
+
+/**
+ * ArticleSection Molecule Component
+ *
+ * A centered content section with a title and constrained max-width,
+ * suitable for article or documentation layouts.
+ */
+
+interface ArticleSectionProps {
+    /** Section title */
+    title: string;
+    /** Section content */
+    children: React.ReactNode;
+    /** Maximum width constraint */
+    maxWidth?: 'sm' | 'md' | 'lg';
+    /** Additional class names */
+    className?: string;
+}
+declare const ArticleSection: React.FC<ArticleSectionProps>;
+
+/**
+ * SimpleGrid Component
+ *
+ * A simplified grid that automatically adjusts columns based on available space.
+ * Perfect for card layouts and item collections.
+ */
+
+type SimpleGridGap = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+interface SimpleGridProps {
+    /** Minimum width of each child (e.g., 200, "200px", "15rem") */
+    minChildWidth?: number | string;
+    /** Maximum number of columns */
+    maxCols?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Exact number of columns (disables auto-fit) */
+    cols?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Gap between items */
+    gap?: SimpleGridGap;
+    /** Custom class name */
+    className?: string;
+    /** Children elements */
+    children: React.ReactNode;
+}
+/**
+ * SimpleGrid - Auto-responsive grid layout
+ */
+declare const SimpleGrid: React.FC<SimpleGridProps>;
+
+/**
+ * MarketingFooter Molecule Component
+ *
+ * A themed footer for marketing/documentation sites.
+ * Displays link columns, optional logo, and copyright text.
+ * Uses @almadar/ui theme CSS variables for consistent branding.
+ */
+
+interface FooterLinkItem {
+    label: string;
+    href: string;
+}
+interface FooterLinkColumn {
+    title: string;
+    items: FooterLinkItem[];
+}
+interface FooterLogo {
+    src: AssetUrl;
+    alt: string;
+    href?: string;
+}
+interface MarketingFooterProps {
+    columns: FooterLinkColumn[];
+    copyright?: string;
+    logo?: FooterLogo;
+    className?: string;
+}
+declare const MarketingFooter: React.FC<MarketingFooterProps>;
+
+/**
+ * GradientDivider Molecule Component
+ *
+ * A horizontal line that fades from transparent at edges to primary color at center.
+ * Used between major sections for visual separation without hard background-color breaks.
+ */
+
+interface GradientDividerProps {
+    /** Semantic palette token or a raw CSS color value. Defaults to 'primary'. */
+    color?: ColorToken | string;
+    /** Additional class names */
+    className?: string;
+}
+declare const GradientDivider: React.FC<GradientDividerProps>;
+
+/**
+ * PullQuote Molecule Component
+ *
+ * Large italic text with a thick left border in primary color.
+ * Breaks up prose walls on long-form pages like Vision and case studies.
+ */
+
+interface PullQuoteProps {
+    /** The quote text */
+    children: string;
+    /** Additional class names */
+    className?: string;
+}
+declare const PullQuote: React.FC<PullQuoteProps>;
+
+/**
+ * AnimatedCounter Molecule Component
+ *
+ * Counts from 0 to a target value on scroll-into-view using IntersectionObserver.
+ * Replaces static stat numbers with animated versions for visual impact.
+ */
+
+interface AnimatedCounterProps {
+    /** Target value to count to. Strings allow display formats (e.g. "500+", "99.9%", "3x"); numbers are coerced. */
+    value: string | number;
+    /** Label displayed below the number */
+    label: string;
+    /** Animation duration in ms */
+    duration?: number;
+    /** Additional class names */
+    className?: string;
+}
+declare const AnimatedCounter: React.FC<AnimatedCounterProps>;
+
+type RevealTrigger = 'scroll' | 'hover' | 'manual';
+type RevealAnimation = 'fade-up' | 'fade-down' | 'fade-in' | 'fade-left' | 'fade-right' | 'scale' | 'scale-up' | 'none';
+interface AnimatedRevealProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children'> {
+    /** Additional CSS classes applied to the root element. */
+    className?: string;
+    /** What triggers the animation */
+    trigger?: RevealTrigger;
+    /** Built-in animation preset */
+    animation?: RevealAnimation;
+    /** Animation duration in ms (default: 600) */
+    duration?: number;
+    /** Delay before animation starts in ms (default: 0) */
+    delay?: number;
+    /** How much of the element must be visible before triggering, 0-1 (default: 0.15) */
+    threshold?: number;
+    /** Animate only the first time the element enters the viewport (default: true) */
+    once?: boolean;
+    /** Manual control: when trigger='manual', set this to true to animate */
+    animate?: boolean;
+    /** Easing function (default: cubic-bezier(0.16, 1, 0.3, 1)) */
+    easing?: string;
+    /** Children: ReactNode or render function receiving animated state */
+    children: React.ReactNode | ((animated: boolean) => React.ReactNode);
+}
+declare const AnimatedReveal: React.ForwardRefExoticComponent<AnimatedRevealProps & React.RefAttributes<HTMLDivElement>>;
+
+type GraphicAnimation = 'draw' | 'fill' | 'pulse' | 'morph';
+interface AnimatedGraphicProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** Additional CSS classes applied to the root element. */
+    className?: string;
+    /** URL to an SVG file. Fetched and inlined to enable stroke/fill animations. */
+    src?: AssetUrl;
+    /** Inline SVG string. Takes precedence over src if both provided. */
+    svgContent?: string;
+    /** Animation type applied to SVG paths/shapes */
+    animation?: GraphicAnimation;
+    /** Whether to run the animation (default: false). Controlled externally or via AnimatedReveal. */
+    animate?: boolean;
+    /** Animation duration in ms (default: 1200) */
+    duration?: number;
+    /** Delay before animation starts in ms (default: 0) */
+    delay?: number;
+    /** Easing function (default: cubic-bezier(0.16, 1, 0.3, 1)) */
+    easing?: string;
+    /** Width of the graphic container */
+    width?: string | number;
+    /** Height of the graphic container */
+    height?: string | number;
+    /** Stroke color override for SVG paths */
+    strokeColor?: string;
+    /** Fill color for the 'fill' animation end state */
+    fillColor?: string;
+    /** Alt text for accessibility */
+    alt?: string;
+}
+declare const AnimatedGraphic: React.ForwardRefExoticComponent<AnimatedGraphicProps & React.RefAttributes<HTMLDivElement>>;
+
+/**
+ * PatternTile Atom
+ *
+ * Mathematically correct Islamic geometric pattern tiles using the
+ * Polygons-in-Contact (PIC) method (Hankin 1925, formalized by Kaplan 2005).
+ *
+ * Construction: A regular polygon tiling is overlaid with star motifs.
+ * Each motif touches the enclosing polygon at EDGE MIDPOINTS only.
+ * Two rays emanate from each midpoint into the polygon at a specific
+ * CONTACT ANGLE (theta). Where rays from adjacent midpoints intersect,
+ * they form the star points. Gap tiles (squares, triangles) between
+ * polygons receive inferred geometry by extending boundary rays inward.
+ *
+ * Variants:
+ *   star8  — 8-fold star-and-cross on 4.8.8 tiling (theta = 67.5 deg)
+ *   star6  — 6-fold star on hexagonal tiling (theta = 60 deg)
+ *   khatam — 8-fold rosette with interlocking kites (theta = 72 deg)
+ *   star10 — 10-fold girih on decagonal tiling (theta = 72 deg)
+ *   star12 — 12-fold on dodecagonal tiling (theta = 75 deg)
+ *
+ * All tiles use stroke only (no fill), rendering as transparent overlays.
+ */
+
+type PatternVariant = 'star8' | 'star6' | 'khatam' | 'star10' | 'star12' | 'rosette-double' | 'rosette-filled' | 'seigaiha' | 'greek-key' | 'celtic-knot' | 'kolam' | 'arch' | 'arabesque-vine' | 'arabesque-net';
+interface PatternTileProps {
+    /** Which geometric pattern to render */
+    variant?: PatternVariant;
+    /** Tile unit size in SVG units */
+    size?: number;
+    /** Stroke color (CSS variable or hex) */
+    color?: string;
+    /** Line thickness */
+    strokeWidth?: number;
+    className?: string;
+}
+declare const PatternTile: React.FC<PatternTileProps>;
+/** Returns the tile dimensions for a given variant and size */
+declare function getTileDimensions(variant: PatternVariant, size: number): {
+    width: number;
+    height: number;
+};
+
+/**
+ * GeometricPattern Molecule
+ *
+ * Composes PatternTile into reusable layout modes for Islamic geometric
+ * background decoration. Supports four modes:
+ *
+ *   background — full tiling fill behind content
+ *   left/right — pattern fades from one side toward the other
+ *   frame      — thin decorative strips above and below content
+ *
+ * Uses SVG <pattern> for efficient tiling and <mask> for fade effects.
+ * All rendering is pure SVG (SSR-safe, no browser APIs).
+ */
+
+interface GeometricPatternProps {
+    /** Which geometric tile design */
+    variant?: PatternVariant;
+    /** Layout mode */
+    mode?: 'background' | 'left' | 'right' | 'dual' | 'around' | 'frame';
+    /** Overall opacity (default: 0.06) */
+    opacity?: number;
+    /** Stroke color passed to PatternTile */
+    color?: string;
+    /** Tile scale multiplier (default: 1) */
+    scale?: number;
+    /** Stroke width passed to PatternTile */
+    strokeWidth?: number;
+    /** Content to wrap (used in frame mode) */
+    children?: React.ReactNode;
+    className?: string;
+}
+declare const GeometricPattern: React.FC<GeometricPatternProps>;
+
+/**
+ * EdgeDecoration Molecule
+ *
+ * Standalone SVG decorative elements positioned on section edges.
+ * Unlike GeometricPattern (which tiles small units), these are large
+ * singular shapes placed at specific positions: left edge, right edge,
+ * or both.
+ *
+ * Variants:
+ *   arch       — Concentric pointed mihrab arches (half-circles opening inward)
+ *   vine       — Flowing arabesque scroll tendrils running vertically
+ *   lattice    — Fine curved diamond lattice mesh
+ *
+ * Each variant renders as an absolutely-positioned SVG on one or both
+ * sides of the parent container.
+ */
+
+type EdgeVariant = 'arch' | 'vine' | 'lattice';
+type EdgeSide = 'left' | 'right' | 'both';
+interface EdgeDecorationProps {
+    /** Which decorative element */
+    variant?: EdgeVariant;
+    /** Which side(s) to place the decoration */
+    side?: EdgeSide;
+    /** Overall opacity (default: 0.15) */
+    opacity?: number;
+    /** Semantic palette token or a raw CSS color value for the stroke. */
+    color?: ColorToken | string;
+    /** Stroke width */
+    strokeWidth?: number;
+    /** Width of the decoration area as percentage of container (default: 15) */
+    width?: number;
+    className?: string;
+}
+declare const EdgeDecoration: React.FC<EdgeDecorationProps>;
+
+export { AnimatedCounter, type AnimatedCounterProps, AnimatedGraphic, type AnimatedGraphicProps, AnimatedReveal, type AnimatedRevealProps, ArticleSection, type ArticleSectionProps, Badge, Box, Button, CTABanner, type CTABannerProps, Card, CaseStudyCard, type CaseStudyCardProps, Center, CommunityLinks, type CommunityLinksProps, ContentSection, type ContentSectionProps, Divider, EdgeDecoration, type EdgeDecorationProps, type EdgeSide, type EdgeVariant, FeatureCard, type FeatureCardProps, FeatureGrid, type FeatureGridProps, type FooterLinkColumn, type FooterLinkItem, GeometricPattern, type GeometricPatternProps, GradientDivider, type GradientDividerProps, type GraphicAnimation, HStack, HeroSection, type HeroSectionProps, Icon, InstallBox, type InstallBoxProps, MarketingFooter, type MarketingFooterProps, PatternTile, type PatternTileProps, type PatternVariant, PricingCard, type PricingCardProps, PricingGrid, type PricingGridProps, PullQuote, type PullQuoteProps, type RevealAnimation, type RevealTrigger, ServiceCatalog, type ServiceCatalogProps, ShowcaseCard, type ShowcaseCardProps, SimpleGrid, Spacer, SplitSection, type SplitSectionProps, StatsGrid, type StatsGridProps, StepFlow, type StepFlowProps, type StepItemProps, TagCloud, type TagCloudProps, TeamCard, type TeamCardProps, Typography, VStack, getTileDimensions };