@hypoth-ui/cli 0.0.1 → 0.1.0

package/templates/hover-card/index.tsx

@@ -0,0 +1,203 @@
+/**
+ * HoverCard compound component exports.
+ *
+ * HoverCard displays rich preview content on hover with configurable delays.
+ *
+ * @example
+ * ```tsx
+ * import { HoverCard } from "@/components/ui";
+ *
+ * <HoverCard.Root>
+ *   <HoverCard.Trigger>
+ *     <a href="/user/123">@johndoe</a>
+ *   </HoverCard.Trigger>
+ *   <HoverCard.Content>
+ *     <img src="avatar.jpg" alt="" />
+ *     <h3>John Doe</h3>
+ *     <p>Software Engineer</p>
+ *   </HoverCard.Content>
+ * </HoverCard.Root>
+ * ```
+ */
+
+import {
+  type HTMLAttributes,
+  type ReactNode,
+  createElement,
+  forwardRef,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type HoverCardPlacement =
+  | "top"
+  | "top-start"
+  | "top-end"
+  | "bottom"
+  | "bottom-start"
+  | "bottom-end"
+  | "left"
+  | "left-start"
+  | "left-end"
+  | "right"
+  | "right-start"
+  | "right-end";
+
+export interface HoverCardRootProps extends HTMLAttributes<HTMLElement> {
+  /** Content */
+  children?: ReactNode;
+  /** Controlled open state */
+  open?: boolean;
+  /** Default open state (uncontrolled) */
+  defaultOpen?: boolean;
+  /** Called when open state changes */
+  onOpenChange?: (open: boolean) => void;
+  /** Placement relative to trigger */
+  placement?: HoverCardPlacement;
+  /** Offset distance from trigger in pixels */
+  offset?: number;
+  /** Whether to flip placement when near viewport edge */
+  flip?: boolean;
+  /** Delay in ms before showing on hover */
+  openDelay?: number;
+  /** Delay in ms before hiding after hover leaves */
+  closeDelay?: number;
+  /** Whether to animate open/close transitions */
+  animated?: boolean;
+}
+
+export interface HoverCardTriggerProps extends HTMLAttributes<HTMLElement> {
+  /** Trigger content */
+  children?: ReactNode;
+}
+
+export interface HoverCardContentProps extends HTMLAttributes<HTMLElement> {
+  /** Content */
+  children?: ReactNode;
+}
+
+// ============================================================================
+// Components
+// ============================================================================
+
+/**
+ * HoverCard root component.
+ */
+const HoverCardRoot = forwardRef<HTMLElement, HoverCardRootProps>(function HoverCardRoot(
+  {
+    children,
+    className,
+    open: controlledOpen,
+    defaultOpen = false,
+    onOpenChange,
+    placement = "bottom",
+    offset = 8,
+    flip = true,
+    openDelay = 700,
+    closeDelay = 300,
+    animated = true,
+    ...props
+  },
+  ref
+) {
+  const [internalOpen, setInternalOpen] = useState(defaultOpen);
+  const isControlled = controlledOpen !== undefined;
+  const open = isControlled ? controlledOpen : internalOpen;
+  const elementRef = useRef<HTMLElement>(null);
+
+  // Combine refs
+  const combinedRef = (node: HTMLElement | null) => {
+    (elementRef as React.MutableRefObject<HTMLElement | null>).current = node;
+    if (typeof ref === "function") {
+      ref(node);
+    } else if (ref) {
+      (ref as React.MutableRefObject<HTMLElement | null>).current = node;
+    }
+  };
+
+  const handleOpenChange = useCallback(
+    (event: Event) => {
+      const customEvent = event as CustomEvent;
+      const isOpen = customEvent.type === "ds:open";
+
+      if (!isControlled) {
+        setInternalOpen(isOpen);
+      }
+      onOpenChange?.(isOpen);
+    },
+    [isControlled, onOpenChange]
+  );
+
+  // Attach event listeners
+  useEffect(() => {
+    const element = elementRef.current;
+    if (!element) return;
+
+    element.addEventListener("ds:open", handleOpenChange);
+    element.addEventListener("ds:close", handleOpenChange);
+
+    return () => {
+      element.removeEventListener("ds:open", handleOpenChange);
+      element.removeEventListener("ds:close", handleOpenChange);
+    };
+  }, [handleOpenChange]);
+
+  return createElement(
+    "ds-hover-card",
+    {
+      ref: combinedRef,
+      class: className,
+      open: open || undefined,
+      placement,
+      offset,
+      flip: flip || undefined,
+      "open-delay": openDelay,
+      "close-delay": closeDelay,
+      animated: animated || undefined,
+      ...props,
+    },
+    children
+  );
+});
+HoverCardRoot.displayName = "HoverCard.Root";
+
+/**
+ * HoverCard trigger component.
+ */
+const HoverCardTrigger = forwardRef<HTMLElement, HoverCardTriggerProps>(function HoverCardTrigger(
+  { children, className, ...props },
+  ref
+) {
+  return createElement("span", { ref, className, slot: "trigger", ...props }, children);
+});
+HoverCardTrigger.displayName = "HoverCard.Trigger";
+
+/**
+ * HoverCard content component.
+ */
+const HoverCardContent = forwardRef<HTMLElement, HoverCardContentProps>(function HoverCardContent(
+  { children, className, ...props },
+  ref
+) {
+  return createElement("ds-hover-card-content", { ref, class: className, ...props }, children);
+});
+HoverCardContent.displayName = "HoverCard.Content";
+
+// ============================================================================
+// Compound Component
+// ============================================================================
+
+export const HoverCard = {
+  Root: HoverCardRoot,
+  Trigger: HoverCardTrigger,
+  Content: HoverCardContent,
+};
+
+// Also export individual components
+export { HoverCardRoot, HoverCardTrigger, HoverCardContent };

package/templates/hover-card/wc/hover-card-content.ts

@@ -0,0 +1,50 @@
+/**
+ * HoverCardContent component - container for hover card content.
+ *
+ * @element ds-hover-card-content
+ *
+ * @slot - Content to display in the hover card
+ *
+ * @attr {string} data-state - Animation state ("open" or "closed")
+ */
+
+import { html } from "lit";
+import { property } from "lit/decorators.js";
+import { DSElement } from "../../base/ds-element.js";
+import { define } from "../../registry/define.js";
+
+export type HoverCardContentState = "open" | "closed";
+
+export class DsHoverCardContent extends DSElement {
+  /** Unique ID for ARIA association */
+  @property({ type: String, reflect: true })
+  override id = "";
+
+  /** Animation state (open or closed) - set by parent */
+  @property({ type: String, reflect: true, attribute: "data-state" })
+  dataState: HoverCardContentState = "closed";
+
+  override connectedCallback(): void {
+    super.connectedCallback();
+
+    // Generate ID if not set
+    if (!this.id) {
+      this.id = `hover-card-content-${crypto.randomUUID().slice(0, 8)}`;
+    }
+
+    // Hidden by default (parent controls visibility)
+    this.setAttribute("hidden", "");
+  }
+
+  override render() {
+    return html`<slot></slot>`;
+  }
+}
+
+define("ds-hover-card-content", DsHoverCardContent);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "ds-hover-card-content": DsHoverCardContent;
+  }
+}

package/templates/hover-card/wc/hover-card.ts

@@ -0,0 +1,382 @@
+/**
+ * HoverCard component - rich preview card that appears on hover.
+ *
+ * Opens on mouseenter/focus with configurable delay, stays open when
+ * pointer moves to the card content.
+ *
+ * @element ds-hover-card
+ *
+ * @slot trigger - Element that triggers the hover card
+ * @slot - Hover card content (ds-hover-card-content)
+ *
+ * @fires ds:open - Fired when hover card opens
+ * @fires ds:close - Fired when hover card closes
+ *
+ * @example
+ * ```html
+ * <ds-hover-card>
+ *   <a slot="trigger" href="/user/123">@johndoe</a>
+ *   <ds-hover-card-content>
+ *     <img src="avatar.jpg" alt="">
+ *     <h3>John Doe</h3>
+ *     <p>Software Engineer</p>
+ *   </ds-hover-card-content>
+ * </ds-hover-card>
+ * ```
+ */
+
+import {
+  type AnchorPosition,
+  type DismissableLayer,
+  type Placement,
+  type Presence,
+  createAnchorPosition,
+  createDismissableLayer,
+  createPresence,
+  prefersReducedMotion,
+} from "@hypoth-ui/primitives-dom";
+import { html } from "lit";
+import { property } from "lit/decorators.js";
+import { DSElement } from "../../base/ds-element.js";
+import { StandardEvents, emitEvent } from "../../events/emit.js";
+import { define } from "../../registry/define.js";
+
+// Import child component to ensure it's registered
+import type { DsHoverCardContent } from "./hover-card-content.js";
+import "./hover-card-content.js";
+
+export class DsHoverCard extends DSElement {
+  /** Whether the hover card is open */
+  @property({ type: Boolean, reflect: true })
+  open = false;
+
+  /** Placement relative to trigger */
+  @property({ type: String, reflect: true })
+  placement: Placement = "bottom";
+
+  /** Offset distance from trigger in pixels */
+  @property({ type: Number })
+  offset = 8;
+
+  /** Whether to flip placement when near viewport edge */
+  @property({ type: Boolean })
+  flip = true;
+
+  /** Delay in ms before showing on hover */
+  @property({ type: Number, attribute: "open-delay" })
+  openDelay = 700;
+
+  /** Delay in ms before hiding after hover leaves */
+  @property({ type: Number, attribute: "close-delay" })
+  closeDelay = 300;
+
+  /** Whether to animate open/close transitions */
+  @property({ type: Boolean })
+  animated = true;
+
+  private anchorPosition: AnchorPosition | null = null;
+  private dismissLayer: DismissableLayer | null = null;
+  private presence: Presence | null = null;
+  private resizeObserver: ResizeObserver | null = null;
+  private scrollHandler: (() => void) | null = null;
+  private openTimer: ReturnType<typeof setTimeout> | null = null;
+  private closeTimer: ReturnType<typeof setTimeout> | null = null;
+  private isHoveringTrigger = false;
+  private isHoveringContent = false;
+
+  override connectedCallback(): void {
+    super.connectedCallback();
+
+    // Listen for hover/focus on trigger
+    this.addEventListener("mouseenter", this.handleTriggerMouseEnter, true);
+    this.addEventListener("mouseleave", this.handleTriggerMouseLeave, true);
+    this.addEventListener("focusin", this.handleFocusIn);
+    this.addEventListener("focusout", this.handleFocusOut);
+
+    // Setup after first render
+    this.updateComplete.then(() => {
+      this.setupTriggerAccessibility();
+    });
+  }
+
+  override disconnectedCallback(): void {
+    super.disconnectedCallback();
+    this.removeEventListener("mouseenter", this.handleTriggerMouseEnter, true);
+    this.removeEventListener("mouseleave", this.handleTriggerMouseLeave, true);
+    this.removeEventListener("focusin", this.handleFocusIn);
+    this.removeEventListener("focusout", this.handleFocusOut);
+    this.clearTimers();
+    this.cleanup();
+  }
+
+  /**
+   * Opens the hover card.
+   */
+  public show(): void {
+    if (this.open) return;
+
+    this.clearTimers();
+    this.open = true;
+    emitEvent(this, StandardEvents.OPEN);
+  }
+
+  /**
+   * Closes the hover card.
+   */
+  public close(): void {
+    if (!this.open) return;
+
+    this.clearTimers();
+
+    const content = this.querySelector("ds-hover-card-content") as DsHoverCardContent | null;
+
+    if (this.animated && content && !prefersReducedMotion()) {
+      this.dismissLayer?.deactivate();
+      this.dismissLayer = null;
+
+      this.presence = createPresence({
+        onExitComplete: () => {
+          this.completeClose();
+        },
+      });
+      this.presence.hide(content);
+    } else {
+      this.cleanup();
+      this.open = false;
+      emitEvent(this, StandardEvents.CLOSE);
+    }
+  }
+
+  private completeClose(): void {
+    this.cleanup();
+    this.open = false;
+    emitEvent(this, StandardEvents.CLOSE);
+  }
+
+  private clearTimers(): void {
+    if (this.openTimer) {
+      clearTimeout(this.openTimer);
+      this.openTimer = null;
+    }
+    if (this.closeTimer) {
+      clearTimeout(this.closeTimer);
+      this.closeTimer = null;
+    }
+  }
+
+  private handleTriggerMouseEnter = (event: MouseEvent): void => {
+    const target = event.target as HTMLElement;
+    const trigger = target.closest('[slot="trigger"]');
+    const content = target.closest("ds-hover-card-content");
+
+    if (trigger && this.contains(trigger)) {
+      this.isHoveringTrigger = true;
+      this.scheduleOpen();
+    } else if (content && this.contains(content)) {
+      this.isHoveringContent = true;
+      this.cancelClose();
+    }
+  };
+
+  private handleTriggerMouseLeave = (event: MouseEvent): void => {
+    const target = event.target as HTMLElement;
+    const trigger = target.closest('[slot="trigger"]');
+    const content = target.closest("ds-hover-card-content");
+
+    if (trigger && this.contains(trigger)) {
+      this.isHoveringTrigger = false;
+      this.scheduleClose();
+    } else if (content && this.contains(content)) {
+      this.isHoveringContent = false;
+      this.scheduleClose();
+    }
+  };
+
+  private handleFocusIn = (event: FocusEvent): void => {
+    const target = event.target as HTMLElement;
+    const trigger = target.closest('[slot="trigger"]');
+
+    if (trigger && this.contains(trigger)) {
+      this.clearTimers();
+      this.show();
+    }
+  };
+
+  private handleFocusOut = (event: FocusEvent): void => {
+    const relatedTarget = event.relatedTarget as HTMLElement | null;
+
+    // Check if focus is moving within the hover card
+    if (relatedTarget && this.contains(relatedTarget)) {
+      return;
+    }
+
+    // Focus left the hover card entirely
+    this.scheduleClose();
+  };
+
+  private scheduleOpen(): void {
+    this.cancelClose();
+
+    if (this.open) return;
+
+    this.openTimer = setTimeout(() => {
+      this.show();
+    }, this.openDelay);
+  }
+
+  private scheduleClose(): void {
+    this.cancelOpen();
+
+    // Don't close if still hovering trigger or content
+    if (this.isHoveringTrigger || this.isHoveringContent) {
+      return;
+    }
+
+    if (!this.open) return;
+
+    this.closeTimer = setTimeout(() => {
+      this.close();
+    }, this.closeDelay);
+  }
+
+  private cancelOpen(): void {
+    if (this.openTimer) {
+      clearTimeout(this.openTimer);
+      this.openTimer = null;
+    }
+  }
+
+  private cancelClose(): void {
+    if (this.closeTimer) {
+      clearTimeout(this.closeTimer);
+      this.closeTimer = null;
+    }
+  }
+
+  private handleDismiss = (): void => {
+    this.close();
+  };
+
+  private setupTriggerAccessibility(): void {
+    const trigger = this.querySelector('[slot="trigger"]');
+    const content = this.querySelector("ds-hover-card-content");
+
+    if (trigger && content) {
+      trigger.setAttribute("aria-haspopup", "true");
+      trigger.setAttribute("aria-expanded", String(this.open));
+      if (content.id) {
+        trigger.setAttribute("aria-controls", content.id);
+      }
+    }
+  }
+
+  private updateTriggerAria(): void {
+    const trigger = this.querySelector('[slot="trigger"]');
+    if (trigger) {
+      trigger.setAttribute("aria-expanded", String(this.open));
+    }
+  }
+
+  private setupPositioning(): void {
+    const trigger = this.querySelector('[slot="trigger"]') as HTMLElement | null;
+    const content = this.querySelector("ds-hover-card-content") as HTMLElement | null;
+
+    if (!trigger || !content) return;
+
+    this.anchorPosition = createAnchorPosition({
+      anchor: trigger,
+      floating: content,
+      placement: this.placement,
+      offset: this.offset,
+      flip: this.flip,
+      onPositionChange: (pos) => {
+        content.setAttribute("data-placement", pos.placement);
+      },
+    });
+
+    this.resizeObserver = new ResizeObserver(() => {
+      this.anchorPosition?.update();
+    });
+    this.resizeObserver.observe(trigger);
+    this.resizeObserver.observe(content);
+
+    this.scrollHandler = () => {
+      this.anchorPosition?.update();
+    };
+    window.addEventListener("scroll", this.scrollHandler, { passive: true });
+    window.addEventListener("resize", this.scrollHandler, { passive: true });
+  }
+
+  private setupDismissLayer(): void {
+    const content = this.querySelector("ds-hover-card-content") as HTMLElement | null;
+    const trigger = this.querySelector('[slot="trigger"]') as HTMLElement | null;
+
+    if (!content) return;
+
+    this.dismissLayer = createDismissableLayer({
+      container: content,
+      excludeElements: trigger ? [trigger] : [],
+      onDismiss: this.handleDismiss,
+      closeOnEscape: true,
+      closeOnOutsideClick: false, // Non-modal, only close on escape
+    });
+    this.dismissLayer.activate();
+  }
+
+  private cleanup(): void {
+    this.anchorPosition?.destroy();
+    this.anchorPosition = null;
+    this.dismissLayer?.deactivate();
+    this.dismissLayer = null;
+    this.presence?.destroy();
+    this.presence = null;
+    this.resizeObserver?.disconnect();
+    this.resizeObserver = null;
+
+    if (this.scrollHandler) {
+      window.removeEventListener("scroll", this.scrollHandler);
+      window.removeEventListener("resize", this.scrollHandler);
+      this.scrollHandler = null;
+    }
+  }
+
+  override async updated(changedProperties: Map<string, unknown>): Promise<void> {
+    super.updated(changedProperties);
+
+    if (changedProperties.has("open")) {
+      this.updateTriggerAria();
+
+      const content = this.querySelector("ds-hover-card-content") as DsHoverCardContent | null;
+
+      if (this.open) {
+        content?.removeAttribute("hidden");
+
+        if (content) {
+          content.dataState = "open";
+        }
+
+        await this.updateComplete;
+
+        this.setupPositioning();
+        this.setupDismissLayer();
+      } else {
+        content?.setAttribute("hidden", "");
+      }
+    }
+  }
+
+  override render() {
+    return html`
+      <slot name="trigger"></slot>
+      <slot></slot>
+    `;
+  }
+}
+
+define("ds-hover-card", DsHoverCard);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "ds-hover-card": DsHoverCard;
+  }
+}

package/templates/hover-card/wc/index.ts

@@ -0,0 +1,6 @@
+/**
+ * HoverCard component exports.
+ */
+
+export { DsHoverCard } from "./hover-card.js";
+export { DsHoverCardContent, type HoverCardContentState } from "./hover-card-content.js";