@almadar/ui 5.62.0 → 5.63.1

package/dist/components/marketing/organisms/CaseStudyOrganism.d.ts

@@ -12,8 +12,17 @@
 import React from 'react';
 import type { EntityWith } from '@almadar/core';
 import type { DisplayStateProps } from '../../core/organisms/types';
+/** The per-case-study entity fields this organism reads (FieldValue-compatible). */
+export interface CaseStudyRow {
+    title: string;
+    description?: string;
+    category?: string;
+    categoryColor?: string;
+    href?: string;
+    linkLabel?: string;
+}
 export interface CaseStudyOrganismProps extends DisplayStateProps {
-    entity?: EntityWith<'title'> | readonly EntityWith<'title'>[];
+    entity?: EntityWith<CaseStudyRow> | readonly EntityWith<CaseStudyRow>[];
     heading?: string;
     subtitle?: string;
 }

package/dist/components/marketing/organisms/FeatureGridOrganism.d.ts

@@ -12,8 +12,17 @@
 import React from 'react';
 import type { EntityWith } from '@almadar/core';
 import type { DisplayStateProps } from '../../core/organisms/types';
+/** The per-feature entity fields this organism reads (FieldValue-compatible; the
+ *  `icon`/`href` are string names/urls, the molecule widens `icon` to `IconInput`). */
+export interface FeatureRow {
+    title: string;
+    icon?: string;
+    description?: string;
+    href?: string;
+    linkLabel?: string;
+}
 export interface FeatureGridOrganismProps extends DisplayStateProps {
-    entity?: EntityWith<'title'> | readonly EntityWith<'title'>[];
+    entity?: EntityWith<FeatureRow> | readonly EntityWith<FeatureRow>[];
     columns?: 2 | 3 | 4 | 6;
     heading?: string;
     subtitle?: string;

package/dist/components/marketing/organisms/HeroOrganism.d.ts

@@ -12,8 +12,31 @@
 import React from 'react';
 import type { EntityWith } from '@almadar/core';
 import type { DisplayStateProps } from '../../core/organisms/types';
+/** A hero CTA: a plain `{ label, href }` object (FieldValue-compatible — a `type`,
+ *  not `interface`, so it's assignable to the entity-row `FieldValue` index sig). */
+export type HeroAction = {
+    label?: string;
+    href?: string;
+};
+/** The hero entity fields this organism reads (FieldValue-compatible; `image` is a plain
+ *  `{ src, alt }` object, the action fields plain `{ label, href }` objects). */
+export interface HeroRow {
+    title: string;
+    tag?: string;
+    titleAccent?: string;
+    subtitle?: string;
+    primaryAction?: HeroAction;
+    secondaryAction?: HeroAction;
+    installCommand?: string;
+    image?: {
+        src?: string;
+        alt?: string;
+    };
+    imagePosition?: 'below' | 'right' | 'background';
+    background?: 'dark' | 'gradient' | 'subtle';
+}
 export interface HeroOrganismProps extends DisplayStateProps {
-    entity?: EntityWith<'title'>;
+    entity?: EntityWith<HeroRow>;
     children?: React.ReactNode;
 }
 export declare const HeroOrganism: React.FC<HeroOrganismProps>;

package/dist/components/marketing/organisms/PricingOrganism.d.ts

@@ -12,8 +12,21 @@
 import React from 'react';
 import type { EntityWith } from '@almadar/core';
 import type { DisplayStateProps } from '../../core/organisms/types';
+/** The per-plan entity fields this organism reads. The organism reads FLAT
+ *  `actionLabel`/`actionHref` (the molecule's PricingCardProps nests them under
+ *  `action`), so this is its own shape, not PricingCardProps. */
+export interface PricingPlanRow {
+    name: string;
+    price: string;
+    description?: string;
+    features?: string[];
+    actionLabel?: string;
+    actionHref?: string;
+    highlighted?: boolean;
+    badge?: string;
+}
 export interface PricingOrganismProps extends DisplayStateProps {
-    entity?: EntityWith<'name' | 'price'> | readonly EntityWith<'name' | 'price'>[];
+    entity?: EntityWith<PricingPlanRow> | readonly EntityWith<PricingPlanRow>[];
     heading?: string;
     subtitle?: string;
 }

package/dist/components/marketing/organisms/ShowcaseOrganism.d.ts

@@ -12,8 +12,21 @@
 import React from 'react';
 import type { EntityWith } from '@almadar/core';
 import type { DisplayStateProps } from '../../core/organisms/types';
+/** The per-showcase entity fields this organism reads (FieldValue-compatible; `image`
+ *  is a plain `{ src, alt }` object, `accentColor` a string). */
+export interface ShowcaseRow {
+    title: string;
+    description?: string;
+    image?: {
+        src?: string;
+        alt?: string;
+    };
+    href?: string;
+    badge?: string;
+    accentColor?: string;
+}
 export interface ShowcaseOrganismProps extends DisplayStateProps {
-    entity?: EntityWith<'title'> | readonly EntityWith<'title'>[];
+    entity?: EntityWith<ShowcaseRow> | readonly EntityWith<ShowcaseRow>[];
     columns?: 2 | 3 | 4;
     heading?: string;
     subtitle?: string;

package/dist/components/marketing/organisms/StatsOrganism.d.ts

@@ -11,8 +11,13 @@
 import React from 'react';
 import type { EntityWith } from '@almadar/core';
 import type { DisplayStateProps } from '../../core/organisms/types';
+/** The per-stat entity fields this organism reads (both required). */
+export interface StatRow {
+    value: string;
+    label: string;
+}
 export interface StatsOrganismProps extends DisplayStateProps {
-    entity?: EntityWith<'value' | 'label'> | readonly EntityWith<'value' | 'label'>[];
+    entity?: EntityWith<StatRow> | readonly EntityWith<StatRow>[];
     columns?: 2 | 3 | 4 | 6;
 }
 export declare const StatsOrganism: React.FC<StatsOrganismProps>;

package/dist/components/marketing/organisms/StepFlowOrganism.d.ts

@@ -11,8 +11,16 @@
 import React from 'react';
 import type { EntityWith } from '@almadar/core';
 import type { DisplayStateProps } from '../../core/organisms/types';
+/** The per-step entity fields this organism reads (FieldValue-compatible; `icon` is a
+ *  string name, the molecule widens it to `IconInput`). */
+export interface StepRow {
+    title: string;
+    number?: number;
+    description?: string;
+    icon?: string;
+}
 export interface StepFlowOrganismProps extends DisplayStateProps {
-    entity?: EntityWith<'title'> | readonly EntityWith<'title'>[];
+    entity?: EntityWith<StepRow> | readonly EntityWith<StepRow>[];
     orientation?: 'horizontal' | 'vertical';
     showConnectors?: boolean;
     heading?: string;

package/dist/components/marketing/organisms/TeamOrganism.d.ts

@@ -11,8 +11,17 @@
 import React from 'react';
 import type { EntityWith } from '@almadar/core';
 import type { DisplayStateProps } from '../../core/organisms/types';
+/** The per-member entity fields this organism reads (FieldValue-compatible;
+ *  `avatar` is a string url/initials). */
+export interface TeamMemberRow {
+    name: string;
+    nameAr?: string;
+    role?: string;
+    bio?: string;
+    avatar?: string;
+}
 export interface TeamOrganismProps extends DisplayStateProps {
-    entity?: EntityWith<'name'> | readonly EntityWith<'name'>[];
+    entity?: EntityWith<TeamMemberRow> | readonly EntityWith<TeamMemberRow>[];
     heading?: string;
     subtitle?: string;
 }

package/dist/docs/index.cjs

@@ -2702,12 +2702,60 @@ var init_useEventBus = __esm({
     };
   }
 });
+function useTapReveal(options = {}) {
+  const { onReveal, onDismiss, refs, enabled = true } = options;
+  const [revealed, setRevealed] = React8.useState(false);
+  const onRevealRef = React8.useRef(onReveal);
+  const onDismissRef = React8.useRef(onDismiss);
+  onRevealRef.current = onReveal;
+  onDismissRef.current = onDismiss;
+  const reveal = React8.useCallback(() => {
+    setRevealed((wasRevealed) => {
+      if (!wasRevealed) onRevealRef.current?.();
+      return true;
+    });
+  }, []);
+  const dismiss = React8.useCallback(() => {
+    setRevealed((wasRevealed) => {
+      if (wasRevealed) onDismissRef.current?.();
+      return false;
+    });
+  }, []);
+  const onPointerDown = React8.useCallback(
+    (e) => {
+      if (!enabled || e.pointerType === "mouse") return;
+      if (revealed) dismiss();
+      else reveal();
+    },
+    [enabled, revealed, reveal, dismiss]
+  );
+  React8.useEffect(() => {
+    if (!revealed || typeof document === "undefined") return;
+    const onDocDown = (ev) => {
+      const target = ev.target;
+      if (!(target instanceof Node)) return;
+      const inside = (refs ?? []).some((r2) => r2.current?.contains(target));
+      if (!inside) dismiss();
+    };
+    const id = setTimeout(() => document.addEventListener("pointerdown", onDocDown), 0);
+    return () => {
+      clearTimeout(id);
+      document.removeEventListener("pointerdown", onDocDown);
+    };
+  }, [revealed, refs, dismiss]);
+  return { revealed, triggerProps: { onPointerDown }, reveal, dismiss };
+}
+var init_useTapReveal = __esm({
+  "hooks/useTapReveal.ts"() {
+  }
+});
 var paddingStyles, paddingXStyles, paddingYStyles, marginStyles, marginXStyles, marginYStyles, bgStyles, roundedStyles, shadowStyles, displayStyles, overflowStyles, positionStyles; exports.Box = void 0;
 var init_Box = __esm({
   "components/core/atoms/Box.tsx"() {
     "use client";
     init_cn();
     init_useEventBus();
+    init_useTapReveal();
     paddingStyles = {
       none: "p-0",
       xs: "p-1",
@@ -2833,10 +2881,12 @@ var init_Box = __esm({
         action,
         actionPayload,
         hoverEvent,
+        tapReveal = true,
         maxWidth,
         onClick,
         onMouseEnter,
         onMouseLeave,
+        onPointerDown,
         ...rest
       }, ref) => {
         const eventBus = useEventBus();
@@ -2859,6 +2909,19 @@ var init_Box = __esm({
           }
           onMouseLeave?.(e);
         }, [hoverEvent, eventBus, onMouseLeave]);
+        const { triggerProps } = useTapReveal({
+          enabled: tapReveal && !!hoverEvent,
+          onReveal: React8.useCallback(() => {
+            if (hoverEvent) eventBus.emit(`UI:${hoverEvent}`, { hovered: true });
+          }, [hoverEvent, eventBus]),
+          onDismiss: React8.useCallback(() => {
+            if (hoverEvent) eventBus.emit(`UI:${hoverEvent}`, { hovered: false });
+          }, [hoverEvent, eventBus])
+        });
+        const handlePointerDown = React8.useCallback((e) => {
+          if (hoverEvent && tapReveal) triggerProps.onPointerDown(e);
+          onPointerDown?.(e);
+        }, [hoverEvent, tapReveal, triggerProps, onPointerDown]);
         const isClickable = action || onClick;
         return React8__default.default.createElement(
           Component,
@@ -2886,6 +2949,7 @@ var init_Box = __esm({
             onClick: isClickable ? handleClick : void 0,
             onMouseEnter: hoverEvent || onMouseEnter ? handleMouseEnter : void 0,
             onMouseLeave: hoverEvent || onMouseLeave ? handleMouseLeave : void 0,
+            onPointerDown: hoverEvent && tapReveal || onPointerDown ? handlePointerDown : void 0,
             style: maxWidth ? { maxWidth, ...rest.style } : rest.style,
             ...rest
           },

package/dist/docs/index.d.cts

@@ -56,6 +56,8 @@ interface BoxProps extends React.HTMLAttributes<HTMLDivElement> {
     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 */

package/dist/docs/index.js

@@ -2660,12 +2660,60 @@ var init_useEventBus = __esm({
     };
   }
 });
+function useTapReveal(options = {}) {
+  const { onReveal, onDismiss, refs, enabled = true } = options;
+  const [revealed, setRevealed] = useState(false);
+  const onRevealRef = useRef(onReveal);
+  const onDismissRef = useRef(onDismiss);
+  onRevealRef.current = onReveal;
+  onDismissRef.current = onDismiss;
+  const reveal = useCallback(() => {
+    setRevealed((wasRevealed) => {
+      if (!wasRevealed) onRevealRef.current?.();
+      return true;
+    });
+  }, []);
+  const dismiss = useCallback(() => {
+    setRevealed((wasRevealed) => {
+      if (wasRevealed) onDismissRef.current?.();
+      return false;
+    });
+  }, []);
+  const onPointerDown = useCallback(
+    (e) => {
+      if (!enabled || e.pointerType === "mouse") return;
+      if (revealed) dismiss();
+      else reveal();
+    },
+    [enabled, revealed, reveal, dismiss]
+  );
+  useEffect(() => {
+    if (!revealed || typeof document === "undefined") return;
+    const onDocDown = (ev) => {
+      const target = ev.target;
+      if (!(target instanceof Node)) return;
+      const inside = (refs ?? []).some((r2) => r2.current?.contains(target));
+      if (!inside) dismiss();
+    };
+    const id = setTimeout(() => document.addEventListener("pointerdown", onDocDown), 0);
+    return () => {
+      clearTimeout(id);
+      document.removeEventListener("pointerdown", onDocDown);
+    };
+  }, [revealed, refs, dismiss]);
+  return { revealed, triggerProps: { onPointerDown }, reveal, dismiss };
+}
+var init_useTapReveal = __esm({
+  "hooks/useTapReveal.ts"() {
+  }
+});
 var paddingStyles, paddingXStyles, paddingYStyles, marginStyles, marginXStyles, marginYStyles, bgStyles, roundedStyles, shadowStyles, displayStyles, overflowStyles, positionStyles, Box;
 var init_Box = __esm({
   "components/core/atoms/Box.tsx"() {
     "use client";
     init_cn();
     init_useEventBus();
+    init_useTapReveal();
     paddingStyles = {
       none: "p-0",
       xs: "p-1",
@@ -2791,10 +2839,12 @@ var init_Box = __esm({
         action,
         actionPayload,
         hoverEvent,
+        tapReveal = true,
         maxWidth,
         onClick,
         onMouseEnter,
         onMouseLeave,
+        onPointerDown,
         ...rest
       }, ref) => {
         const eventBus = useEventBus();
@@ -2817,6 +2867,19 @@ var init_Box = __esm({
           }
           onMouseLeave?.(e);
         }, [hoverEvent, eventBus, onMouseLeave]);
+        const { triggerProps } = useTapReveal({
+          enabled: tapReveal && !!hoverEvent,
+          onReveal: useCallback(() => {
+            if (hoverEvent) eventBus.emit(`UI:${hoverEvent}`, { hovered: true });
+          }, [hoverEvent, eventBus]),
+          onDismiss: useCallback(() => {
+            if (hoverEvent) eventBus.emit(`UI:${hoverEvent}`, { hovered: false });
+          }, [hoverEvent, eventBus])
+        });
+        const handlePointerDown = useCallback((e) => {
+          if (hoverEvent && tapReveal) triggerProps.onPointerDown(e);
+          onPointerDown?.(e);
+        }, [hoverEvent, tapReveal, triggerProps, onPointerDown]);
         const isClickable = action || onClick;
         return React8.createElement(
           Component,
@@ -2844,6 +2907,7 @@ var init_Box = __esm({
             onClick: isClickable ? handleClick : void 0,
             onMouseEnter: hoverEvent || onMouseEnter ? handleMouseEnter : void 0,
             onMouseLeave: hoverEvent || onMouseLeave ? handleMouseLeave : void 0,
+            onPointerDown: hoverEvent && tapReveal || onPointerDown ? handlePointerDown : void 0,
             style: maxWidth ? { maxWidth, ...rest.style } : rest.style,
             ...rest
           },

package/dist/hooks/index.cjs

@@ -2516,6 +2516,152 @@ function usePinchZoom(options = {}) {
     resetZoom
   };
 }
+function localPoint(canvas, clientX, clientY) {
+  if (!canvas) return { x: clientX, y: clientY };
+  const rect = canvas.getBoundingClientRect();
+  return { x: clientX - rect.left, y: clientY - rect.top };
+}
+function useCanvasGestures(options) {
+  const {
+    canvasRef,
+    enabled = true,
+    wheelStep = 1.1,
+    onPointerDown,
+    onPointerMove,
+    onPointerUp,
+    onZoom,
+    onPanDelta,
+    onMultiTouchStart
+  } = options;
+  const pointers = react.useRef(/* @__PURE__ */ new Map());
+  const pinch = react.useRef(null);
+  const computePinch = react.useCallback(() => {
+    const pts = [...pointers.current.values()];
+    const dx = pts[1].x - pts[0].x;
+    const dy = pts[1].y - pts[0].y;
+    return {
+      distance: Math.hypot(dx, dy) || 1,
+      centroid: { x: (pts[0].x + pts[1].x) / 2, y: (pts[0].y + pts[1].y) / 2 }
+    };
+  }, []);
+  const handlePointerDown = react.useCallback(
+    (e) => {
+      if (!enabled) return;
+      e.currentTarget.setPointerCapture(e.pointerId);
+      pointers.current.set(e.pointerId, localPoint(canvasRef.current, e.clientX, e.clientY));
+      if (pointers.current.size === 2) {
+        onMultiTouchStart?.();
+        pinch.current = computePinch();
+      } else if (pointers.current.size === 1) {
+        onPointerDown?.(e);
+      }
+    },
+    [enabled, canvasRef, onMultiTouchStart, computePinch, onPointerDown]
+  );
+  const handlePointerMove = react.useCallback(
+    (e) => {
+      if (!enabled) return;
+      if (pointers.current.has(e.pointerId)) {
+        pointers.current.set(e.pointerId, localPoint(canvasRef.current, e.clientX, e.clientY));
+      }
+      if (pointers.current.size >= 2 && pinch.current) {
+        const next = computePinch();
+        const prev = pinch.current;
+        if (next.distance !== prev.distance) {
+          onZoom?.(next.distance / prev.distance, next.centroid.x, next.centroid.y);
+        }
+        onPanDelta?.(next.centroid.x - prev.centroid.x, next.centroid.y - prev.centroid.y);
+        pinch.current = next;
+        return;
+      }
+      onPointerMove?.(e);
+    },
+    [enabled, canvasRef, computePinch, onZoom, onPanDelta, onPointerMove]
+  );
+  const endPointer = react.useCallback(
+    (e, fireUp) => {
+      const wasMulti = pointers.current.size >= 2;
+      pointers.current.delete(e.pointerId);
+      if (pointers.current.size < 2) pinch.current = null;
+      if (wasMulti && pointers.current.size === 1) return;
+      if (pointers.current.size === 0 && fireUp) onPointerUp?.(e);
+    },
+    [onPointerUp]
+  );
+  const handlePointerUp = react.useCallback(
+    (e) => {
+      if (!enabled) return;
+      endPointer(e, true);
+    },
+    [enabled, endPointer]
+  );
+  const handlePointerCancel = react.useCallback(
+    (e) => {
+      if (!enabled) return;
+      endPointer(e, false);
+    },
+    [enabled, endPointer]
+  );
+  const handleWheel = react.useCallback(
+    (e) => {
+      if (!enabled) return;
+      e.preventDefault();
+      const { x, y } = localPoint(canvasRef.current, e.clientX, e.clientY);
+      onZoom?.(e.deltaY < 0 ? wheelStep : 1 / wheelStep, x, y);
+    },
+    [enabled, canvasRef, wheelStep, onZoom]
+  );
+  return {
+    onPointerDown: handlePointerDown,
+    onPointerMove: handlePointerMove,
+    onPointerUp: handlePointerUp,
+    onPointerCancel: handlePointerCancel,
+    onWheel: handleWheel
+  };
+}
+function useTapReveal(options = {}) {
+  const { onReveal, onDismiss, refs, enabled = true } = options;
+  const [revealed, setRevealed] = react.useState(false);
+  const onRevealRef = react.useRef(onReveal);
+  const onDismissRef = react.useRef(onDismiss);
+  onRevealRef.current = onReveal;
+  onDismissRef.current = onDismiss;
+  const reveal = react.useCallback(() => {
+    setRevealed((wasRevealed) => {
+      if (!wasRevealed) onRevealRef.current?.();
+      return true;
+    });
+  }, []);
+  const dismiss = react.useCallback(() => {
+    setRevealed((wasRevealed) => {
+      if (wasRevealed) onDismissRef.current?.();
+      return false;
+    });
+  }, []);
+  const onPointerDown = react.useCallback(
+    (e) => {
+      if (!enabled || e.pointerType === "mouse") return;
+      if (revealed) dismiss();
+      else reveal();
+    },
+    [enabled, revealed, reveal, dismiss]
+  );
+  react.useEffect(() => {
+    if (!revealed || typeof document === "undefined") return;
+    const onDocDown = (ev) => {
+      const target = ev.target;
+      if (!(target instanceof Node)) return;
+      const inside = (refs ?? []).some((r) => r.current?.contains(target));
+      if (!inside) dismiss();
+    };
+    const id = setTimeout(() => document.addEventListener("pointerdown", onDocDown), 0);
+    return () => {
+      clearTimeout(id);
+      document.removeEventListener("pointerdown", onDocDown);
+    };
+  }, [revealed, refs, dismiss]);
+  return { revealed, triggerProps: { onPointerDown }, reveal, dismiss };
+}
 var ALMADAR_DND_MIME = "application/x-almadar-dnd";
 function useDraggable({ payload, disabled = false }) {
   const [isDragging, setIsDragging] = react.useState(false);
@@ -2767,6 +2913,7 @@ exports.updateEntity = updateEntity;
 exports.updateSingleton = updateSingleton;
 exports.useAgentChat = useAgentChat;
 exports.useAuthContext = useAuthContext;
+exports.useCanvasGestures = useCanvasGestures;
 exports.useCompile = useCompile;
 exports.useConnectGitHub = useConnectGitHub;
 exports.useDeepAgentGeneration = useDeepAgentGeneration;
@@ -2800,6 +2947,7 @@ exports.useQuerySingleton = useQuerySingleton;
 exports.useRenderInterpolation = useRenderInterpolation;
 exports.useSingletonEntity = useSingletonEntity;
 exports.useSwipeGesture = useSwipeGesture;
+exports.useTapReveal = useTapReveal;
 exports.useTraitListens = useTraitListens;
 exports.useTranslate = useTranslate;
 exports.useUIEvents = useUIEvents;

package/dist/hooks/index.d.ts

@@ -24,6 +24,8 @@ export { useDragReorder, type DragReorderResult, } from './useDragReorder';
 export { useInfiniteScroll, type InfiniteScrollOptions, type InfiniteScrollResult, } from './useInfiniteScroll';
 export { usePullToRefresh, type PullToRefreshOptions, type PullToRefreshResult, } from './usePullToRefresh';
 export { usePinchZoom, type PinchZoomOptions, type PinchZoomResult, } from './usePinchZoom';
+export { useCanvasGestures, type UseCanvasGesturesOptions, type CanvasGestureCallbacks, type CanvasGestureHandlers, } from './useCanvasGestures';
+export { useTapReveal, type TapRevealOptions, type TapRevealResult, } from './useTapReveal';
 export { useDraggable, ALMADAR_DND_MIME, type DraggablePayload, type UseDraggableOptions, type UseDraggableResult, } from './useDraggable';
 export { useDropZone, type UseDropZoneOptions, type UseDropZoneResult, } from './useDropZone';
 export { useRenderInterpolation, type Positioned, type RenderInterpolationOptions, type RenderInterpolationHandle, } from './useRenderInterpolation';