@almadar/ui 6.59.0 → 6.62.0

package/dist/ssr/index.d.cts

@@ -2,6 +2,9 @@ import React from 'react';
 import { A11yProps, EventKey, EventPayload, EventEmit, Asset, AssetUrl, SurfaceMode, SkeletonSpec } from '@almadar/core';
 import { LucideIcon } from 'lucide-react';
 
+type BandEdge = 'none' | 'curve' | 'wave' | 'arc' | 'tilt' | 'step' | 'scallop';
+type BandEdgeColor = 'background' | 'muted' | 'surface' | 'gradient' | 'inverse';
+
 /**
  * Box Component
  *
@@ -11,7 +14,7 @@ import { LucideIcon } from 'lucide-react';
 
 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 BoxBg = "transparent" | "primary" | "secondary" | "muted" | "accent" | "surface" | "overlay" | "gradient" | "inverse";
 type BoxRounded = "none" | "sm" | "md" | "lg" | "xl" | "2xl" | "full";
 type BoxShadow = "none" | "sm" | "md" | "lg" | "xl";
 interface BoxProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof A11yProps>, A11yProps {
@@ -63,7 +66,10 @@ interface BoxProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof A11y
      *  @payloadFor action
      */
     actionPayload?: EventPayload;
-    /** Declarative hover event — emits UI:{hoverEvent} with { hovered: true/false } on mouseEnter/mouseLeave */
+    /**
+     * Declarative hover event — emits UI:{hoverEvent} with { hovered: true/false } on mouseEnter/mouseLeave
+     * @notification
+     */
     hoverEvent?: EventEmit<{
         hovered: boolean;
     }>;
@@ -71,6 +77,20 @@ interface BoxProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof A11y
     tapReveal?: boolean;
     /** Maximum width (CSS value, e.g., "550px", "80rem") */
     maxWidth?: string;
+    /** Shape cut into the top edge of a full-width band; "curve" uses the theme's shape */
+    edgeTop?: BandEdge;
+    /** Shape cut into the bottom edge of a full-width band; "curve" uses the theme's shape */
+    edgeBottom?: BandEdge;
+    /** Surface of the neighbouring band, which fills the cut */
+    edgeColor?: BandEdgeColor;
+    /** Mirror the edge shapes horizontally */
+    edgeFlip?: boolean;
+    /** Lay the theme's texture over the band */
+    texture?: boolean;
+    /** Content that appears or changes inside the box eases in instead of switching in one frame (new rows, swapped views, changed text), played in presentation motion (the theme's dramatic duration, standard easing) so it can be watched. Off under reduced motion. */
+    animateChanges?: boolean;
+    /** Scene behind the band's content (photo, illustration, pattern); never takes clicks */
+    backdrop?: React.ReactNode;
     /** Children elements */
     children?: React.ReactNode;
 }
@@ -115,7 +135,10 @@ interface StackProps extends Omit<React.AriaAttributes, keyof A11yProps>, A11yPr
     as?: React.ElementType;
     /** Click handler */
     onClick?: (e: React.MouseEvent) => void;
-    /** Keyboard handler */
+    /**
+     * Keyboard handler
+     * @notification
+     */
     onKeyDown?: (e: React.KeyboardEvent) => void;
     /** Element id */
     id?: string;
@@ -292,7 +315,7 @@ declare const Icon: React.FC<IconProps>;
 type ButtonVariant = "primary" | "secondary" | "ghost" | "danger" | "success" | "warning" | "default" | "link";
 type ButtonSize = "sm" | "md" | "lg";
 /** @accessibleName label */
-interface ButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, keyof A11yProps>, A11yProps {
+interface ButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, keyof A11yProps | 'onClick'>, A11yProps {
     /** Additional CSS classes applied to the root element. */
     className?: string;
     variant?: ButtonVariant;
@@ -323,6 +346,11 @@ interface ButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>
     disabled?: boolean;
     /** Makes the button a link: `#anchor` scrolls, an absolute URL loads, a path navigates in-app */
     href?: string;
+    /**
+     * Runs on activation, on the button or, with `href`, on the link; calling
+     * `preventDefault()` there keeps a link from following its `href`.
+     */
+    onClick?: (event: React.MouseEvent<HTMLButtonElement | HTMLAnchorElement>) => void;
     /** Test identifier for automated tests */
     'data-testid'?: string;
 }
@@ -498,6 +526,7 @@ declare const Avatar: React.FC<AvatarProps>;
 type ImageFit = 'cover' | 'contain' | 'fill' | 'none';
 type ImageAspect = 'auto' | '1/1' | '4/3' | '3/2' | '16/9' | '21/9';
 type ImageRounded = 'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full';
+type ImagePosition = 'center' | 'top' | 'bottom' | 'left' | 'right';
 /** @accessibleName alt */
 interface ImageProps extends A11yProps {
     /** Image source URL */
@@ -514,6 +543,14 @@ interface ImageProps extends A11yProps {
     bordered?: boolean;
     /** "lazy" defers off-screen images; "eager" for above-the-fold media */
     loading?: 'lazy' | 'eager';
+    /** Which part of the image stays visible when it is cropped */
+    position?: ImagePosition;
+    /** Candidate sources at different widths (the HTML `srcset`) */
+    srcSet?: string;
+    /** Rendered widths at each breakpoint (the HTML `sizes`) */
+    sizes?: string;
+    /** The page's main image: load it first */
+    priority?: boolean;
     /** Additional class names */
     className?: string;
 }
@@ -702,6 +739,21 @@ interface AnimatedRevealProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
     delay?: number;
     /** How much of the element must be visible before triggering, 0-1 (default: 0.15) */
     threshold?: number;
+    /**
+     * scroll trigger: event emitted once (as UI:{revealEvent}) the first time the element scrolls into view; never under reduced motion
+     * @notification
+     */
+    revealEvent?: EventKey;
+    /**
+     * scroll trigger: event emitted (as UI:{enterEvent}) every time the element enters the view
+     * @notification
+     */
+    enterEvent?: EventKey;
+    /**
+     * scroll trigger: event emitted (as UI:{leaveEvent}) every time the element leaves the view after having entered it
+     * @notification
+     */
+    leaveEvent?: EventKey;
     /** 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 */

package/dist/ssr/index.d.ts

@@ -2,6 +2,9 @@ import React from 'react';
 import { A11yProps, EventKey, EventPayload, EventEmit, Asset, AssetUrl, SurfaceMode, SkeletonSpec } from '@almadar/core';
 import { LucideIcon } from 'lucide-react';
 
+type BandEdge = 'none' | 'curve' | 'wave' | 'arc' | 'tilt' | 'step' | 'scallop';
+type BandEdgeColor = 'background' | 'muted' | 'surface' | 'gradient' | 'inverse';
+
 /**
  * Box Component
  *
@@ -11,7 +14,7 @@ import { LucideIcon } from 'lucide-react';
 
 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 BoxBg = "transparent" | "primary" | "secondary" | "muted" | "accent" | "surface" | "overlay" | "gradient" | "inverse";
 type BoxRounded = "none" | "sm" | "md" | "lg" | "xl" | "2xl" | "full";
 type BoxShadow = "none" | "sm" | "md" | "lg" | "xl";
 interface BoxProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof A11yProps>, A11yProps {
@@ -63,7 +66,10 @@ interface BoxProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof A11y
      *  @payloadFor action
      */
     actionPayload?: EventPayload;
-    /** Declarative hover event — emits UI:{hoverEvent} with { hovered: true/false } on mouseEnter/mouseLeave */
+    /**
+     * Declarative hover event — emits UI:{hoverEvent} with { hovered: true/false } on mouseEnter/mouseLeave
+     * @notification
+     */
     hoverEvent?: EventEmit<{
         hovered: boolean;
     }>;
@@ -71,6 +77,20 @@ interface BoxProps extends Omit<React.HTMLAttributes<HTMLDivElement>, keyof A11y
     tapReveal?: boolean;
     /** Maximum width (CSS value, e.g., "550px", "80rem") */
     maxWidth?: string;
+    /** Shape cut into the top edge of a full-width band; "curve" uses the theme's shape */
+    edgeTop?: BandEdge;
+    /** Shape cut into the bottom edge of a full-width band; "curve" uses the theme's shape */
+    edgeBottom?: BandEdge;
+    /** Surface of the neighbouring band, which fills the cut */
+    edgeColor?: BandEdgeColor;
+    /** Mirror the edge shapes horizontally */
+    edgeFlip?: boolean;
+    /** Lay the theme's texture over the band */
+    texture?: boolean;
+    /** Content that appears or changes inside the box eases in instead of switching in one frame (new rows, swapped views, changed text), played in presentation motion (the theme's dramatic duration, standard easing) so it can be watched. Off under reduced motion. */
+    animateChanges?: boolean;
+    /** Scene behind the band's content (photo, illustration, pattern); never takes clicks */
+    backdrop?: React.ReactNode;
     /** Children elements */
     children?: React.ReactNode;
 }
@@ -115,7 +135,10 @@ interface StackProps extends Omit<React.AriaAttributes, keyof A11yProps>, A11yPr
     as?: React.ElementType;
     /** Click handler */
     onClick?: (e: React.MouseEvent) => void;
-    /** Keyboard handler */
+    /**
+     * Keyboard handler
+     * @notification
+     */
     onKeyDown?: (e: React.KeyboardEvent) => void;
     /** Element id */
     id?: string;
@@ -292,7 +315,7 @@ declare const Icon: React.FC<IconProps>;
 type ButtonVariant = "primary" | "secondary" | "ghost" | "danger" | "success" | "warning" | "default" | "link";
 type ButtonSize = "sm" | "md" | "lg";
 /** @accessibleName label */
-interface ButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, keyof A11yProps>, A11yProps {
+interface ButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, keyof A11yProps | 'onClick'>, A11yProps {
     /** Additional CSS classes applied to the root element. */
     className?: string;
     variant?: ButtonVariant;
@@ -323,6 +346,11 @@ interface ButtonProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>
     disabled?: boolean;
     /** Makes the button a link: `#anchor` scrolls, an absolute URL loads, a path navigates in-app */
     href?: string;
+    /**
+     * Runs on activation, on the button or, with `href`, on the link; calling
+     * `preventDefault()` there keeps a link from following its `href`.
+     */
+    onClick?: (event: React.MouseEvent<HTMLButtonElement | HTMLAnchorElement>) => void;
     /** Test identifier for automated tests */
     'data-testid'?: string;
 }
@@ -498,6 +526,7 @@ declare const Avatar: React.FC<AvatarProps>;
 type ImageFit = 'cover' | 'contain' | 'fill' | 'none';
 type ImageAspect = 'auto' | '1/1' | '4/3' | '3/2' | '16/9' | '21/9';
 type ImageRounded = 'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full';
+type ImagePosition = 'center' | 'top' | 'bottom' | 'left' | 'right';
 /** @accessibleName alt */
 interface ImageProps extends A11yProps {
     /** Image source URL */
@@ -514,6 +543,14 @@ interface ImageProps extends A11yProps {
     bordered?: boolean;
     /** "lazy" defers off-screen images; "eager" for above-the-fold media */
     loading?: 'lazy' | 'eager';
+    /** Which part of the image stays visible when it is cropped */
+    position?: ImagePosition;
+    /** Candidate sources at different widths (the HTML `srcset`) */
+    srcSet?: string;
+    /** Rendered widths at each breakpoint (the HTML `sizes`) */
+    sizes?: string;
+    /** The page's main image: load it first */
+    priority?: boolean;
     /** Additional class names */
     className?: string;
 }
@@ -702,6 +739,21 @@ interface AnimatedRevealProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
     delay?: number;
     /** How much of the element must be visible before triggering, 0-1 (default: 0.15) */
     threshold?: number;
+    /**
+     * scroll trigger: event emitted once (as UI:{revealEvent}) the first time the element scrolls into view; never under reduced motion
+     * @notification
+     */
+    revealEvent?: EventKey;
+    /**
+     * scroll trigger: event emitted (as UI:{enterEvent}) every time the element enters the view
+     * @notification
+     */
+    enterEvent?: EventKey;
+    /**
+     * scroll trigger: event emitted (as UI:{leaveEvent}) every time the element leaves the view after having entered it
+     * @notification
+     */
+    leaveEvent?: EventKey;
     /** 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 */