@olwiba/ui 0.2.18 → 0.2.20

package/dist/index.d.ts

@@ -579,11 +579,60 @@ declare const marketingSectionSpacing: {
 };
 type MarketingSectionSpacing = keyof typeof marketingSectionSpacing;
 
+/**
+ * How a marketing section sits on the page.
+ *
+ * Every section used to hard-code the same island — an opaque `bg-card` panel
+ * with a border and a radius — which is right for a page that is only its
+ * sections, and wrong for one with an ambient background behind it: a run of
+ * opaque slabs blocks the thing that makes the page feel alive.
+ *
+ * - `'card'` — the opaque island. Contained, high contrast, reads as a panel.
+ * - `'soft'` — translucent and blurred. Still a shape, but the page behind it
+ *   shows through, which is the treatment that works over an aura or gradient.
+ * - `'plain'` — no panel at all. The content sits directly on the page.
+ *
+ * `'card'` stays the default so nothing changes for a page that never sets it.
+ */
+type MarketingSurface = 'card' | 'soft' | 'plain';
+/**
+ * Sets the default surface for every marketing section beneath it.
+ *
+ * Page-level rather than per-section because "this page has an ambient
+ * background, so its sections should not be opaque" is one decision, and making
+ * it once beats repeating it on every section and having a new section silently
+ * default back to an island.
+ */
+declare function MarketingSurfaceProvider({ surface, children, }: {
+    surface: MarketingSurface | undefined;
+    children: React.ReactNode;
+}): react_jsx_runtime.JSX.Element;
+declare function useMarketingSurface(): MarketingSurface | undefined;
+/**
+ * The section wrapper's classes for the resolved surface and UI mode.
+ *
+ * `overflow-hidden` is unconditional on every surface, including `'plain'` —
+ * the marquee and carousel sections clip their own content against it, so
+ * dropping it with the panel would let them bleed across the page.
+ *
+ * Resolution order is prop, then `MarketingSurfaceProvider`, then `'card'`.
+ * Both context reads happen every render rather than short-circuiting on the
+ * prop: `modeProp ?? useHook()` skips a hook call and changes hook order
+ * between renders, which is the exact bug @olwiba/cn 0.1.28 and 0.1.30 fixed in
+ * `Toaster` and `Input`.
+ *
+ * Only `smooth`, `playful` and unset are branched on. olwibaCN's source has a
+ * fourth `glass` variant, but the published `UIVariant` type does not carry it
+ * yet, so a branch for it does not typecheck here.
+ */
+declare function useSectionSurface(override?: MarketingSurface): string;
+
 interface HeroSectionProps {
     heading: string;
     badge?: string;
     description: string;
-    primaryCta: {
+    /** Ignored when `primarySlot` is given. */
+    primaryCta?: {
         label: string;
         href: string;
     };
@@ -591,6 +640,18 @@ interface HeroSectionProps {
         label: string;
         href: string;
     };
+    /**
+     * Replaces the primary button with your own control — a search field, a
+     * short form, an email capture.
+     *
+     * A hero whose first action *is* the product converts better than one that
+     * links to a page where the product starts. `secondaryCta` still renders
+     * beside it, so "…or see pricing" survives.
+     *
+     * Rendered full-width above the secondary CTA on small screens, since a
+     * field sharing a row with a button gets squeezed to nothing on a phone.
+     */
+    primarySlot?: React.ReactNode;
     heroImage?: React.ReactNode;
     media?: 'image' | 'phone' | 'none';
     phoneSize?: 'sm' | 'md' | 'lg';
@@ -598,7 +659,7 @@ interface HeroSectionProps {
     socialProofText?: string;
     renderLink?: AppShellRenderLink;
 }
-declare function HeroSection({ heading, badge, description, primaryCta, secondaryCta, heroImage, media, phoneSize, avatarUrls, socialProofText, renderLink, }: HeroSectionProps): react_jsx_runtime.JSX.Element;
+declare function HeroSection({ heading, badge, description, primaryCta, secondaryCta, primarySlot, heroImage, media, phoneSize, avatarUrls, socialProofText, renderLink, }: HeroSectionProps): react_jsx_runtime.JSX.Element;
 
 interface FeaturesSectionProps {
     title?: string;
@@ -612,8 +673,10 @@ interface FeaturesSectionProps {
     }>;
     /** How the feature cards are arranged. @default 'grid' */
     layout?: 'grid' | 'carousel';
+    /** How the section sits on the page. @default 'card' */
+    surface?: MarketingSurface;
 }
-declare function FeaturesSection({ title, description, badge, features, layout, }: FeaturesSectionProps): react_jsx_runtime.JSX.Element;
+declare function FeaturesSection({ title, description, badge, features, layout, surface, }: FeaturesSectionProps): react_jsx_runtime.JSX.Element;
 
 interface GroupedFeatureGroup {
     label: string;
@@ -629,8 +692,10 @@ interface GroupedFeaturesSectionProps {
     title?: string;
     description?: string;
     groups: GroupedFeatureGroup[];
+    /** How the section sits on the page. @default 'card' */
+    surface?: MarketingSurface;
 }
-declare function GroupedFeaturesSection({ badge, title, description, groups, }: GroupedFeaturesSectionProps): react_jsx_runtime.JSX.Element;
+declare function GroupedFeaturesSection({ badge, title, description, groups, surface, }: GroupedFeaturesSectionProps): react_jsx_runtime.JSX.Element;
 
 interface StepItem {
     emoji?: string;
@@ -651,8 +716,10 @@ interface StepsSectionProps {
     variant?: 'default' | 'timeline';
     /** Timeline only — step groups with optional interstitial content; overrides `steps`. Numbering continues across groups. */
     groups?: StepGroup[];
+    /** How the section sits on the page. @default 'card' */
+    surface?: MarketingSurface;
 }
-declare function StepsSection({ badge, title, description, steps, variant, groups, }: StepsSectionProps): react_jsx_runtime.JSX.Element;
+declare function StepsSection({ badge, title, description, steps, variant, groups, surface, }: StepsSectionProps): react_jsx_runtime.JSX.Element;
 
 interface TechStackItem {
     icon: LucideIcon;
@@ -665,8 +732,10 @@ interface TechStackSectionProps {
     title?: string;
     description?: string;
     items: TechStackItem[];
+    /** How the section sits on the page. @default 'card' */
+    surface?: MarketingSurface;
 }
-declare function TechStackSection({ badge, title, description, items, }: TechStackSectionProps): react_jsx_runtime.JSX.Element;
+declare function TechStackSection({ badge, title, description, items, surface, }: TechStackSectionProps): react_jsx_runtime.JSX.Element;
 
 interface FeatureMarqueeItem {
     icon: LucideIcon;
@@ -683,8 +752,10 @@ interface FeatureMarqueeSectionProps {
     rows: FeatureMarqueeRow[];
     speed?: 'slow' | 'normal' | 'fast';
     pauseOnHover?: boolean;
+    /** How the section sits on the page. @default 'card' */
+    surface?: MarketingSurface;
 }
-declare function FeatureMarqueeSection({ badge, title, description, rows, speed, pauseOnHover, }: FeatureMarqueeSectionProps): react_jsx_runtime.JSX.Element;
+declare function FeatureMarqueeSection({ badge, title, description, rows, speed, pauseOnHover, surface, }: FeatureMarqueeSectionProps): react_jsx_runtime.JSX.Element;
 
 interface CtaSectionProps {
     heading: string;
@@ -708,6 +779,8 @@ interface CtaSectionProps {
     /** (showcase) Watermark icon rendered behind the content. @default <Rocket /> */
     icon?: React.ReactNode;
     renderLink?: AppShellRenderLink;
+    /** How the section sits on the page. @default 'card' */
+    surface?: MarketingSurface;
 }
 declare function CtaSection(props: CtaSectionProps): react_jsx_runtime.JSX.Element;
 
@@ -877,8 +950,16 @@ interface PricingSectionProps {
      * mode.
      */
     priceEffect?: PricingCardProps['priceEffect'];
+    /**
+     * How the section sits on the page. @default 'card'
+     *
+     * Named `surface` rather than following the `mode` convention the other
+     * sections use, because `mode` on this component already means
+     * subscription-vs-one-time.
+     */
+    surface?: MarketingSurface;
 }
-declare function PricingSection({ title, description, badge, plans, saveBadge, isAuthenticated, renderLink, footnote, mode, foundingDeadline, currency, highlightedBadgeLabel, renderPlanFooter, cadences, defaultCadence, onSelectPlan, pendingPlanName, priceEffect, }: PricingSectionProps): react_jsx_runtime.JSX.Element;
+declare function PricingSection({ title, description, badge, plans, saveBadge, isAuthenticated, renderLink, footnote, mode, foundingDeadline, currency, highlightedBadgeLabel, renderPlanFooter, cadences, defaultCadence, onSelectPlan, pendingPlanName, priceEffect, surface, }: PricingSectionProps): react_jsx_runtime.JSX.Element;
 
 interface TestimonialsSectionProps {
     title?: string;
@@ -893,8 +974,10 @@ interface TestimonialsSectionProps {
         initials?: string;
         rating?: number;
     }>;
+    /** How the section sits on the page. @default 'card' */
+    surface?: MarketingSurface;
 }
-declare function TestimonialsSection({ title, description, badge, testimonials, }: TestimonialsSectionProps): react_jsx_runtime.JSX.Element;
+declare function TestimonialsSection({ title, description, badge, testimonials, surface, }: TestimonialsSectionProps): react_jsx_runtime.JSX.Element;
 
 interface TeamMember {
     name: string;
@@ -913,8 +996,10 @@ interface TeamSectionProps {
     badge?: string;
     title?: string;
     description?: string;
+    /** How the section sits on the page. @default 'card' */
+    surface?: MarketingSurface;
 }
-declare function TeamSection({ members, badge, title, description, }: TeamSectionProps): react_jsx_runtime.JSX.Element;
+declare function TeamSection({ members, badge, title, description, surface, }: TeamSectionProps): react_jsx_runtime.JSX.Element;
 
 interface FaqSectionProps {
     title?: string;
@@ -924,8 +1009,10 @@ interface FaqSectionProps {
         question: string;
         answer: string;
     }>;
+    /** How the section sits on the page. @default 'card' */
+    surface?: MarketingSurface;
 }
-declare function FaqSection({ title, description, badge, items, }: FaqSectionProps): react_jsx_runtime.JSX.Element;
+declare function FaqSection({ title, description, badge, items, surface, }: FaqSectionProps): react_jsx_runtime.JSX.Element;
 
 interface StatsSectionProps {
     title?: string;
@@ -936,8 +1023,10 @@ interface StatsSectionProps {
         label: string;
         description?: string;
     }>;
+    /** How the section sits on the page. @default 'card' */
+    surface?: MarketingSurface;
 }
-declare function StatsSection({ title, description, badge, stats, }: StatsSectionProps): react_jsx_runtime.JSX.Element;
+declare function StatsSection({ title, description, badge, stats, surface, }: StatsSectionProps): react_jsx_runtime.JSX.Element;
 
 interface NewsletterSectionProps {
     badge?: string;
@@ -950,8 +1039,10 @@ interface NewsletterSectionProps {
     successTitle?: string;
     successDescription?: string;
     onSubscribe?: (email: string) => void | Promise<void>;
+    /** How the section sits on the page. @default 'card' */
+    surface?: MarketingSurface;
 }
-declare function NewsletterSection({ badge, title, description, placeholder, submitLabel, privacyHref, privacyLabel, successTitle, successDescription, onSubscribe, }?: NewsletterSectionProps): react_jsx_runtime.JSX.Element;
+declare function NewsletterSection({ badge, title, description, placeholder, submitLabel, privacyHref, privacyLabel, successTitle, successDescription, onSubscribe, surface, }?: NewsletterSectionProps): react_jsx_runtime.JSX.Element;
 
 type ContactInfoItem = {
     label: string;
@@ -968,8 +1059,10 @@ interface ContactSectionProps {
     successDescription?: string;
     sendAnotherLabel?: string;
     onSubmit?: (event: React.FormEvent<HTMLFormElement>) => void | Promise<void>;
+    /** How the section sits on the page. @default 'card' */
+    surface?: MarketingSurface;
 }
-declare function ContactSection({ badge, title, description, contactInfo, privacyHref, successTitle, successDescription, sendAnotherLabel, onSubmit, }?: ContactSectionProps): react_jsx_runtime.JSX.Element;
+declare function ContactSection({ badge, title, description, contactInfo, privacyHref, successTitle, successDescription, sendAnotherLabel, onSubmit, surface, }?: ContactSectionProps): react_jsx_runtime.JSX.Element;
 
 interface ComparisonColumn {
     label: string;
@@ -983,8 +1076,10 @@ interface ComparisonSectionProps {
     title?: string;
     description?: string;
     columns: ComparisonColumn[];
+    /** How the section sits on the page. @default 'card' */
+    surface?: MarketingSurface;
 }
-declare function ComparisonSection({ badge, title, description, columns, }: ComparisonSectionProps): react_jsx_runtime.JSX.Element;
+declare function ComparisonSection({ badge, title, description, columns, surface, }: ComparisonSectionProps): react_jsx_runtime.JSX.Element;
 
 interface QualificationColumn {
     heading: string;
@@ -996,8 +1091,10 @@ interface QualificationSectionProps {
     title?: string;
     description?: string;
     columns: [QualificationColumn, QualificationColumn];
+    /** How the section sits on the page. @default 'card' */
+    surface?: MarketingSurface;
 }
-declare function QualificationSection({ badge, title, description, columns, }: QualificationSectionProps): react_jsx_runtime.JSX.Element;
+declare function QualificationSection({ badge, title, description, columns, surface, }: QualificationSectionProps): react_jsx_runtime.JSX.Element;
 
 interface NavbarProps {
     brand: {
@@ -1998,4 +2095,4 @@ interface UsePaginationReturn {
 }
 declare function usePagination(total: number, pageSize: number): UsePaginationReturn;
 
-export { ActivityFeed, type ActivityFeedItem, type ActivityFeedProps, AnimatedPill, type AnimatedPillProps, AnimatedSwap, type AnimatedSwapEffect, type AnimatedSwapProps, type AnimatedSwapSpec, AppContent, type AppContentProps, AppGrid, AppGridCell, type AppGridCellProps, type AppGridColumns, type AppGridProps, type AppNavItem, AppPageHero, type AppPageHeroProps, AppScreen, AppShell, type AppShellAction, type AppShellBrand, type AppShellProps, type AppShellRenderLink, type AppShellUser, type AuthFormProps, AuthSection, type AuthSectionProps, Badge, type BadgeProps, type BillingInvoice, BillingPanel, type BillingPanelProps, type BillingPaymentMethod, type BillingUsageMetric, BrandColorSwitchMinimal, Button, type ButtonProps, Card, type CardProps, Carousel, type CarouselProps, ChangelogCard, type ChangelogCardProps, type ChangelogHighlight, ChangelogList, type ChangelogListProps, type ChangelogReleaseType, Chart, type ChartProps, type ChartSeries, Checkbox, type CheckboxProps, CommandMenu, type CommandMenuGroup, type CommandMenuItem, type CommandMenuProps, type ComparisonColumn, ComparisonSection, type ComparisonSectionProps, ConfirmDialog, type ConfirmDialogProps, type ConfirmOptions, type ContactInfoItem, ContactSection, type ContactSectionProps, ContextMenu, type ContextMenuDef, type ContextMenuProps, CountUp, type CountUpProps, CountdownTimer, type CountdownTimerProps, CtaSection, type CtaSectionProps, DataTable, type DataTableProps, DataView, type DataViewProps, DevBanner, type DevBannerProps, Dock, type DockItem, type DockProps, EmptyState, type EmptyStateProps, ErrorPage, type ErrorPageProps, FadeIn, type FadeInProps, FaqSection, type FaqSectionProps, FeatureCard, type FeatureCardProps, type FeatureMarqueeItem, type FeatureMarqueeRow, FeatureMarqueeSection, type FeatureMarqueeSectionProps, FeaturesSection, type FeaturesSectionProps, FileUpload, type FileUploadEntry, type FileUploadProps, FlowBracket, type FlowBracketProps, FlowConnector, type FlowConnectorProps, Footer, type FooterProps, FullPageSpinner, GlassCard, type GlassCardProps, Grid, GridItem, type GridItemProps, type GridProps, type GroupedFeatureGroup, GroupedFeaturesSection, type GroupedFeaturesSectionProps, HeroSection, type HeroSectionProps, type Hotkey, ImageCard, type ImageCardProps, Input, type InputProps, LogoStrip, type LogoStripProps, type MarketingSectionSpacing, MediaCard, type MediaCardProps, ModeSwitchMinimal, Navbar, type NavbarProps, NewsletterSection, type NewsletterSectionProps, type NotificationItem, NotificationToast, type NotificationToastProps, NotificationsPopover, type NotificationsPopoverProps, type NotifyAction, type NotifyOptions, OlwibaUIProvider, type OlwibaUIProviderProps, type OnboardingStep, OnboardingWizard, type OnboardingWizardProps, Overlay, type OverlayProps, type OverlayVariant, PageHeader, type PageHeaderBackButton, type PageHeaderBreadcrumb, type PageHeaderProps, PageTransition, type PageTransitionProps, PhoneFrame, type PhoneFrameProps, type PostAuthor, PostCard, type PostCardProps, PostList, type PostListProps, PricingCard, type PricingCardProps, type PricingFeature, type PricingPlan, PricingSection, type PricingSectionProps, PublicPageFrame, type PublicPageFrameProps, type QualificationColumn, QualificationSection, type QualificationSectionProps, RegisterHotkeys, RootErrorFallback, Section, type SectionProps, SectionTitle, type SectionTitleProps, SettingsSection, type SettingsSectionProps, Sortable, type SortableProps, Spotlight, type SpotlightGroup, type SpotlightItem, type SpotlightProps, Stack, type StackProps, StaggerChildren, type StaggerChildrenProps, StatCard, type StatCardProps, StatsSection, type StatsSectionProps, type StepGroup, type StepItem, StepsSection, type StepsSectionProps, Suspensed, Switch, type SwitchProps, type TeamMember, type TeamMemberRecord, TeamMembersPanel, type TeamMembersPanelProps, TeamSection, type TeamSectionProps, type TechStackItem, TechStackSection, type TechStackSectionProps, TestimonialCard, type TestimonialCardProps, TestimonialsSection, type TestimonialsSectionProps, Textarea, type TextareaProps, ThemeColorUpdater, ThemeSwitchMinimal, type UIMode, Underlay, type UnderlayProps, type UnderlayVariant, UpdateBanner, type UpdateBannerProps, type UpgradeComparisonRow, UpgradePrompt, type UpgradePromptProps, type UseConfirmReturn, type UseControlledOpenReturn, type UsePaginationReturn, type UseViewModeReturn, VersionBanner, type ViewMode, ViewToggle, type ViewToggleProps, cn, marketingSectionSpacing, notify, useConfirm, useControlledOpen, useCopyToClipboard, useDebounce, useIntersectionObserver, useLocalStorage, useMediaQuery, useMounted, useOlwibaUI, usePagination, useScrolledPast, useUIMode, useViewMode };
+export { ActivityFeed, type ActivityFeedItem, type ActivityFeedProps, AnimatedPill, type AnimatedPillProps, AnimatedSwap, type AnimatedSwapEffect, type AnimatedSwapProps, type AnimatedSwapSpec, AppContent, type AppContentProps, AppGrid, AppGridCell, type AppGridCellProps, type AppGridColumns, type AppGridProps, type AppNavItem, AppPageHero, type AppPageHeroProps, AppScreen, AppShell, type AppShellAction, type AppShellBrand, type AppShellProps, type AppShellRenderLink, type AppShellUser, type AuthFormProps, AuthSection, type AuthSectionProps, Badge, type BadgeProps, type BillingInvoice, BillingPanel, type BillingPanelProps, type BillingPaymentMethod, type BillingUsageMetric, BrandColorSwitchMinimal, Button, type ButtonProps, Card, type CardProps, Carousel, type CarouselProps, ChangelogCard, type ChangelogCardProps, type ChangelogHighlight, ChangelogList, type ChangelogListProps, type ChangelogReleaseType, Chart, type ChartProps, type ChartSeries, Checkbox, type CheckboxProps, CommandMenu, type CommandMenuGroup, type CommandMenuItem, type CommandMenuProps, type ComparisonColumn, ComparisonSection, type ComparisonSectionProps, ConfirmDialog, type ConfirmDialogProps, type ConfirmOptions, type ContactInfoItem, ContactSection, type ContactSectionProps, ContextMenu, type ContextMenuDef, type ContextMenuProps, CountUp, type CountUpProps, CountdownTimer, type CountdownTimerProps, CtaSection, type CtaSectionProps, DataTable, type DataTableProps, DataView, type DataViewProps, DevBanner, type DevBannerProps, Dock, type DockItem, type DockProps, EmptyState, type EmptyStateProps, ErrorPage, type ErrorPageProps, FadeIn, type FadeInProps, FaqSection, type FaqSectionProps, FeatureCard, type FeatureCardProps, type FeatureMarqueeItem, type FeatureMarqueeRow, FeatureMarqueeSection, type FeatureMarqueeSectionProps, FeaturesSection, type FeaturesSectionProps, FileUpload, type FileUploadEntry, type FileUploadProps, FlowBracket, type FlowBracketProps, FlowConnector, type FlowConnectorProps, Footer, type FooterProps, FullPageSpinner, GlassCard, type GlassCardProps, Grid, GridItem, type GridItemProps, type GridProps, type GroupedFeatureGroup, GroupedFeaturesSection, type GroupedFeaturesSectionProps, HeroSection, type HeroSectionProps, type Hotkey, ImageCard, type ImageCardProps, Input, type InputProps, LogoStrip, type LogoStripProps, type MarketingSectionSpacing, type MarketingSurface, MarketingSurfaceProvider, MediaCard, type MediaCardProps, ModeSwitchMinimal, Navbar, type NavbarProps, NewsletterSection, type NewsletterSectionProps, type NotificationItem, NotificationToast, type NotificationToastProps, NotificationsPopover, type NotificationsPopoverProps, type NotifyAction, type NotifyOptions, OlwibaUIProvider, type OlwibaUIProviderProps, type OnboardingStep, OnboardingWizard, type OnboardingWizardProps, Overlay, type OverlayProps, type OverlayVariant, PageHeader, type PageHeaderBackButton, type PageHeaderBreadcrumb, type PageHeaderProps, PageTransition, type PageTransitionProps, PhoneFrame, type PhoneFrameProps, type PostAuthor, PostCard, type PostCardProps, PostList, type PostListProps, PricingCard, type PricingCardProps, type PricingFeature, type PricingPlan, PricingSection, type PricingSectionProps, PublicPageFrame, type PublicPageFrameProps, type QualificationColumn, QualificationSection, type QualificationSectionProps, RegisterHotkeys, RootErrorFallback, Section, type SectionProps, SectionTitle, type SectionTitleProps, SettingsSection, type SettingsSectionProps, Sortable, type SortableProps, Spotlight, type SpotlightGroup, type SpotlightItem, type SpotlightProps, Stack, type StackProps, StaggerChildren, type StaggerChildrenProps, StatCard, type StatCardProps, StatsSection, type StatsSectionProps, type StepGroup, type StepItem, StepsSection, type StepsSectionProps, Suspensed, Switch, type SwitchProps, type TeamMember, type TeamMemberRecord, TeamMembersPanel, type TeamMembersPanelProps, TeamSection, type TeamSectionProps, type TechStackItem, TechStackSection, type TechStackSectionProps, TestimonialCard, type TestimonialCardProps, TestimonialsSection, type TestimonialsSectionProps, Textarea, type TextareaProps, ThemeColorUpdater, ThemeSwitchMinimal, type UIMode, Underlay, type UnderlayProps, type UnderlayVariant, UpdateBanner, type UpdateBannerProps, type UpgradeComparisonRow, UpgradePrompt, type UpgradePromptProps, type UseConfirmReturn, type UseControlledOpenReturn, type UsePaginationReturn, type UseViewModeReturn, VersionBanner, type ViewMode, ViewToggle, type ViewToggleProps, cn, marketingSectionSpacing, notify, useConfirm, useControlledOpen, useCopyToClipboard, useDebounce, useIntersectionObserver, useLocalStorage, useMarketingSurface, useMediaQuery, useMounted, useOlwibaUI, usePagination, useScrolledPast, useSectionSurface, useUIMode, useViewMode };