@hypoth-ui/cli 0.0.1 → 0.1.0

package/templates/alert-dialog/wc/alert-dialog.ts

@@ -0,0 +1,302 @@
+/**
+ * AlertDialog component - modal dialog requiring explicit user action.
+ *
+ * AlertDialog is used for important decisions that require confirmation.
+ * Unlike Dialog, it cannot be dismissed by clicking outside or pressing Escape.
+ *
+ * Implements WAI-ARIA AlertDialog pattern.
+ *
+ * @element ds-alert-dialog
+ *
+ * @slot trigger - Button or element that opens the alert dialog
+ * @slot - AlertDialog content (ds-alert-dialog-content)
+ *
+ * @fires ds:open - Fired when alert dialog opens
+ * @fires ds:close - Fired when alert dialog closes
+ *
+ * @example
+ * ```html
+ * <ds-alert-dialog>
+ *   <button slot="trigger">Delete Account</button>
+ *   <ds-alert-dialog-content>
+ *     <ds-alert-dialog-header>
+ *       <ds-alert-dialog-title>Are you absolutely sure?</ds-alert-dialog-title>
+ *       <ds-alert-dialog-description>
+ *         This action cannot be undone.
+ *       </ds-alert-dialog-description>
+ *     </ds-alert-dialog-header>
+ *     <ds-alert-dialog-footer>
+ *       <ds-alert-dialog-cancel>Cancel</ds-alert-dialog-cancel>
+ *       <ds-alert-dialog-action>Delete</ds-alert-dialog-action>
+ *     </ds-alert-dialog-footer>
+ *   </ds-alert-dialog-content>
+ * </ds-alert-dialog>
+ * ```
+ */
+
+import {
+  type DialogBehavior,
+  type Presence,
+  createDialogBehavior,
+  createPresence,
+  prefersReducedMotion,
+} from "@hypoth-ui/primitives-dom";
+import { html } from "lit";
+import { property, state } 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 { devWarn, hasRequiredChild, Warnings } from "../../utils/dev-warnings.js";
+
+// Import child components to ensure they're registered
+import type { DsAlertDialogContent } from "./alert-dialog-content.js";
+import "./alert-dialog-content.js";
+import "./alert-dialog-header.js";
+import "./alert-dialog-footer.js";
+import "./alert-dialog-title.js";
+import "./alert-dialog-description.js";
+import "./alert-dialog-action.js";
+import "./alert-dialog-cancel.js";
+
+export class DsAlertDialog extends DSElement {
+  /** Whether the alert dialog is open */
+  @property({ type: Boolean, reflect: true })
+  open = false;
+
+  /** Whether to animate open/close transitions */
+  @property({ type: Boolean })
+  animated = true;
+
+  /** Whether the alert dialog is closing (for animation) */
+  @state()
+  private isClosing = false;
+
+  private dialogBehavior: DialogBehavior | null = null;
+  private presence: Presence | null = null;
+
+  override connectedCallback(): void {
+    super.connectedCallback();
+
+    // Listen for trigger clicks via event delegation
+    this.addEventListener("click", this.handleTriggerClick);
+
+    // Listen for action/cancel clicks
+    this.addEventListener("ds:alert-dialog-action", this.handleAction as EventListener);
+    this.addEventListener("ds:alert-dialog-cancel", this.handleCancel as EventListener);
+
+    // Initialize dialog behavior (AlertDialog does NOT close on escape or outside click)
+    this.initDialogBehavior();
+  }
+
+  override disconnectedCallback(): void {
+    super.disconnectedCallback();
+    this.removeEventListener("click", this.handleTriggerClick);
+    this.removeEventListener("ds:alert-dialog-action", this.handleAction as EventListener);
+    this.removeEventListener("ds:alert-dialog-cancel", this.handleCancel as EventListener);
+    this.cleanup();
+  }
+
+  /**
+   * Initializes the dialog behavior primitive.
+   * AlertDialog uses role="alertdialog" and disables dismiss on escape/outside click.
+   */
+  private initDialogBehavior(): void {
+    this.dialogBehavior = createDialogBehavior({
+      defaultOpen: this.open,
+      role: "alertdialog",
+      closeOnEscape: false, // AlertDialog does NOT close on escape
+      closeOnOutsideClick: false, // AlertDialog does NOT close on outside click
+      onOpenChange: () => {
+        // AlertDialog only closes via explicit action/cancel buttons
+        // so we don't handle behavior-initiated closes here
+      },
+    });
+
+    // Set trigger element if one exists
+    const trigger = this.querySelector('[slot="trigger"]') as HTMLElement | null;
+    if (trigger) {
+      this.dialogBehavior.setTriggerElement(trigger);
+    }
+  }
+
+  /**
+   * Opens the alert dialog.
+   */
+  public show(): void {
+    if (this.open) return;
+
+    // Store trigger element for focus return
+    const trigger = this.querySelector('[slot="trigger"]') as HTMLElement | null;
+    if (trigger) {
+      this.dialogBehavior?.setTriggerElement(trigger);
+    } else if (document.activeElement instanceof HTMLElement) {
+      this.dialogBehavior?.setTriggerElement(document.activeElement);
+    }
+
+    this.open = true;
+    this.dialogBehavior?.open();
+    emitEvent(this, StandardEvents.OPEN);
+  }
+
+  /**
+   * Closes the alert dialog.
+   */
+  public close(): void {
+    if (!this.open) return;
+
+    const content = this.querySelector("ds-alert-dialog-content") as DsAlertDialogContent | null;
+
+    // Close the behavior (deactivates focus trap and dismiss layer)
+    this.dialogBehavior?.close();
+
+    // If animated, use presence for exit animation
+    if (this.animated && content && !prefersReducedMotion()) {
+      this.isClosing = true;
+
+      // Create presence for exit animation
+      this.presence = createPresence({
+        onExitComplete: () => {
+          this.completeClose();
+        },
+      });
+      this.presence.hide(content);
+    } else {
+      // No animation - close immediately
+      this.open = false;
+      this.isClosing = false;
+      emitEvent(this, StandardEvents.CLOSE);
+    }
+  }
+
+  /**
+   * Completes the close after exit animation.
+   */
+  private completeClose(): void {
+    this.presence?.destroy();
+    this.presence = null;
+    this.open = false;
+    this.isClosing = false;
+    emitEvent(this, StandardEvents.CLOSE);
+  }
+
+  private handleTriggerClick = (event: Event): void => {
+    const target = event.target as HTMLElement;
+    const trigger = target.closest('[slot="trigger"]');
+
+    if (trigger && this.contains(trigger)) {
+      // Store trigger before opening
+      this.dialogBehavior?.setTriggerElement(trigger as HTMLElement);
+      this.show();
+    }
+  };
+
+  private handleAction = (): void => {
+    // Action clicked - close the dialog
+    this.close();
+  };
+
+  private handleCancel = (): void => {
+    // Cancel clicked - close the dialog
+    this.close();
+  };
+
+  private cleanup(): void {
+    this.dialogBehavior?.destroy();
+    this.dialogBehavior = null;
+    this.presence?.destroy();
+    this.presence = null;
+  }
+
+  override async updated(changedProperties: Map<string, unknown>): Promise<void> {
+    super.updated(changedProperties);
+
+    if (changedProperties.has("open")) {
+      const content = this.querySelector("ds-alert-dialog-content") as DsAlertDialogContent | null;
+
+      if (this.open) {
+        // Wait for the next microtask to ensure DOM is committed
+        await this.updateComplete;
+
+        // Set data-state to open for entry animation
+        if (content) {
+          content.dataState = "open";
+        }
+
+        // Set content element on behavior (activates focus trap and dismiss layer)
+        this.dialogBehavior?.setContentElement(content);
+        this.updateContentAccessibility();
+      } else {
+        // Clear content element on behavior
+        this.dialogBehavior?.setContentElement(null);
+      }
+    }
+  }
+
+  /**
+   * Updates accessibility attributes on alert dialog content.
+   */
+  private updateContentAccessibility(): void {
+    const content = this.querySelector("ds-alert-dialog-content");
+    if (!content || !this.dialogBehavior) return;
+
+    // Get props from behavior
+    const contentProps = this.dialogBehavior.getContentProps();
+
+    // Set role on content - always alertdialog
+    content.setAttribute("role", "alertdialog");
+    content.setAttribute("aria-modal", contentProps["aria-modal"]);
+
+    // Dev warning: Check for required alert dialog title
+    if (!hasRequiredChild(this, "ds-alert-dialog-title") && !this.getAttribute("aria-label")) {
+      devWarn(Warnings.dialogMissingTitle("ds-alert-dialog"));
+    }
+
+    // Connect title via aria-labelledby
+    const title = this.querySelector("ds-alert-dialog-title");
+    if (title) {
+      const titleProps = this.dialogBehavior.getTitleProps();
+      if (!title.id) {
+        title.id = titleProps.id;
+      }
+      content.setAttribute("aria-labelledby", title.id);
+    }
+
+    // Connect description via aria-describedby
+    const description = this.querySelector("ds-alert-dialog-description");
+    if (description) {
+      const descProps = this.dialogBehavior.getDescriptionProps();
+      if (!description.id) {
+        description.id = descProps.id;
+      }
+      content.setAttribute("aria-describedby", description.id);
+      this.dialogBehavior.setHasDescription(true);
+    } else {
+      // Dev warning: Title without description
+      if (title) {
+        devWarn(Warnings.dialogMissingDescription("ds-alert-dialog"));
+      }
+      this.dialogBehavior.setHasDescription(false);
+    }
+  }
+
+  override render() {
+    return html`
+      <slot name="trigger"></slot>
+      <div
+        class="ds-alert-dialog__backdrop"
+        ?hidden=${!this.open}
+        ?data-closing=${this.isClosing}
+      >
+        <slot></slot>
+      </div>
+    `;
+  }
+}
+
+define("ds-alert-dialog", DsAlertDialog);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "ds-alert-dialog": DsAlertDialog;
+  }
+}

package/templates/alert-dialog/wc/index.ts

@@ -0,0 +1,13 @@
+/**
+ * AlertDialog component exports.
+ */
+
+export { DsAlertDialog } from "./alert-dialog.js";
+export { DsAlertDialogTrigger } from "./alert-dialog-trigger.js";
+export { DsAlertDialogContent, type AlertDialogContentSize } from "./alert-dialog-content.js";
+export { DsAlertDialogHeader } from "./alert-dialog-header.js";
+export { DsAlertDialogFooter } from "./alert-dialog-footer.js";
+export { DsAlertDialogTitle } from "./alert-dialog-title.js";
+export { DsAlertDialogDescription } from "./alert-dialog-description.js";
+export { DsAlertDialogAction } from "./alert-dialog-action.js";
+export { DsAlertDialogCancel } from "./alert-dialog-cancel.js";

package/templates/aspect-ratio/index.tsx

@@ -0,0 +1,50 @@
+/**
+ * AspectRatio component React wrapper.
+ *
+ * @example
+ * ```tsx
+ * import { AspectRatio } from "@/components/ui";
+ *
+ * <AspectRatio ratio="16/9">
+ *   <img src="image.jpg" alt="..." />
+ * </AspectRatio>
+ * ```
+ */
+
+import { type HTMLAttributes, type ReactNode, createElement, forwardRef } from "react";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export interface AspectRatioProps extends HTMLAttributes<HTMLElement> {
+  /** Content to maintain aspect ratio */
+  children?: ReactNode;
+  /**
+   * Aspect ratio as width/height (e.g., "16/9", "4/3", "1/1").
+   * Can also be a number (e.g., 1.777 for 16:9).
+   */
+  ratio?: string | number;
+}
+
+// ============================================================================
+// Component
+// ============================================================================
+
+/**
+ * AspectRatio component - maintains consistent width-to-height ratio.
+ */
+export const AspectRatio = forwardRef<HTMLElement, AspectRatioProps>(function AspectRatio(
+  { children, className, ratio = "1/1", ...props },
+  ref
+) {
+  const ratioString = typeof ratio === "number" ? String(ratio) : ratio;
+
+  return createElement(
+    "ds-aspect-ratio",
+    { ref, class: className, ratio: ratioString, ...props },
+    children
+  );
+});
+
+AspectRatio.displayName = "AspectRatio";

package/templates/aspect-ratio/wc/aspect-ratio.ts

@@ -0,0 +1,78 @@
+/**
+ * AspectRatio component - maintains consistent width-to-height ratio.
+ *
+ * @element ds-aspect-ratio
+ *
+ * @slot - Default slot for content to maintain aspect ratio
+ *
+ * @example
+ * ```html
+ * <ds-aspect-ratio ratio="16/9">
+ *   <img src="image.jpg" alt="..." />
+ * </ds-aspect-ratio>
+ * <ds-aspect-ratio ratio="4/3">
+ *   <video src="video.mp4"></video>
+ * </ds-aspect-ratio>
+ * ```
+ */
+
+import { html } from "lit";
+import { property } from "lit/decorators.js";
+import { DSElement } from "../../base/ds-element.js";
+import { define } from "../../registry/define.js";
+
+export class DsAspectRatio extends DSElement {
+  /**
+   * Aspect ratio as width/height (e.g., "16/9", "4/3", "1/1").
+   * Can also be a number (e.g., 1.777 for 16:9).
+   */
+  @property({ reflect: true })
+  ratio = "1/1";
+
+  override updated(): void {
+    this.updateCssVariable();
+  }
+
+  override connectedCallback(): void {
+    super.connectedCallback();
+    this.updateCssVariable();
+  }
+
+  private updateCssVariable(): void {
+    const ratioValue = this.parseRatio(this.ratio);
+    this.style.setProperty("--ds-aspect-ratio", String(ratioValue));
+  }
+
+  private parseRatio(ratio: string): number {
+    // Handle fraction format like "16/9"
+    if (ratio.includes("/")) {
+      const parts = ratio.split("/").map(Number);
+      const width = parts[0];
+      const height = parts[1];
+      if (
+        width !== undefined &&
+        height !== undefined &&
+        !Number.isNaN(width) &&
+        !Number.isNaN(height) &&
+        height !== 0
+      ) {
+        return width / height;
+      }
+    }
+    // Handle decimal format
+    const parsed = Number.parseFloat(ratio);
+    return Number.isNaN(parsed) ? 1 : parsed;
+  }
+
+  override render() {
+    return html`<slot></slot>`;
+  }
+}
+
+define("ds-aspect-ratio", DsAspectRatio);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "ds-aspect-ratio": DsAspectRatio;
+  }
+}

package/templates/aspect-ratio/wc/index.ts

@@ -0,0 +1,5 @@
+/**
+ * AspectRatio component barrel exports.
+ */
+
+export { DsAspectRatio } from "./aspect-ratio.js";

package/templates/avatar/avatar-group.tsx

@@ -0,0 +1,88 @@
+"use client";
+
+import { type HTMLAttributes, type ReactNode, createElement, forwardRef } from "react";
+import "@hypoth-ui/wc";
+import {
+  type ResponsiveProp,
+  generateResponsiveDataAttr,
+  isResponsiveObject,
+  resolveResponsiveValue,
+} from "../../primitives/responsive.js";
+import type { AvatarSize } from "./avatar.js";
+
+export interface AvatarGroupProps extends HTMLAttributes<HTMLElement> {
+  /**
+   * Maximum number of avatars to display before showing overflow.
+   * @default 5
+   */
+  max?: number;
+
+  /**
+   * Size variant (inherited by child avatars) - supports responsive object syntax.
+   * @default "md"
+   * @example
+   * ```tsx
+   * // Single value
+   * <AvatarGroup size="md">...</AvatarGroup>
+   *
+   * // Responsive
+   * <AvatarGroup size={{ base: "sm", md: "lg" }}>...</AvatarGroup>
+   * ```
+   */
+  size?: ResponsiveProp<AvatarSize>;
+
+  /**
+   * Avatar children.
+   */
+  children?: ReactNode;
+}
+
+/**
+ * Avatar group component for displaying multiple avatars with overflow indicator.
+ *
+ * @example
+ * ```tsx
+ * <AvatarGroup max={3}>
+ *   <Avatar name="Alice" />
+ *   <Avatar name="Bob" />
+ *   <Avatar name="Charlie" />
+ *   <Avatar name="Diana" />
+ *   <Avatar name="Eve" />
+ * </AvatarGroup>
+ * // Shows 3 avatars + "+2" overflow indicator
+ * ```
+ */
+export const AvatarGroup = forwardRef<HTMLElement, AvatarGroupProps>(function AvatarGroup(
+  { max = 5, size = "md", children, className, ...props },
+  ref
+) {
+  // Resolve responsive size - use base value for the WC attribute
+  const resolvedSize = resolveResponsiveValue(size, "md");
+  const isResponsive = isResponsiveObject(size);
+  const responsiveSizeAttr = isResponsive ? generateResponsiveDataAttr(size) : undefined;
+
+  return createElement(
+    "ds-avatar-group",
+    {
+      ref,
+      max,
+      size: resolvedSize,
+      class: className,
+      // Add responsive data attribute for CSS targeting
+      "data-size-responsive": responsiveSizeAttr,
+      ...props,
+    },
+    children
+  );
+});
+
+// TypeScript declaration for JSX
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      "ds-avatar-group": AvatarGroupProps & {
+        ref?: React.Ref<HTMLElement>;
+      };
+    }
+  }
+}

package/templates/avatar/avatar.tsx

@@ -0,0 +1,124 @@
+"use client";
+
+import { type HTMLAttributes, createElement, forwardRef } from "react";
+import "@hypoth-ui/wc";
+import {
+  type ResponsiveProp,
+  generateResponsiveDataAttr,
+  isResponsiveObject,
+  resolveResponsiveValue,
+} from "../../primitives/responsive.js";
+
+export type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
+export type AvatarShape = "circle" | "square";
+export type AvatarStatus = "online" | "offline" | "away" | "busy";
+
+export interface AvatarProps extends Omit<HTMLAttributes<HTMLElement>, "children"> {
+  /**
+   * Image source URL.
+   */
+  src?: string;
+
+  /**
+   * Alt text for image.
+   */
+  alt?: string;
+
+  /**
+   * User's name (used for initials fallback).
+   */
+  name?: string;
+
+  /**
+   * Size variant - supports responsive object syntax.
+   * @default "md"
+   * @example
+   * ```tsx
+   * // Single value
+   * <Avatar name="John Doe" size="md" />
+   *
+   * // Responsive
+   * <Avatar name="John Doe" size={{ base: "sm", md: "lg" }} />
+   * ```
+   */
+  size?: ResponsiveProp<AvatarSize>;
+
+  /**
+   * Shape variant.
+   * @default "circle"
+   */
+  shape?: AvatarShape;
+
+  /**
+   * Status indicator.
+   */
+  status?: AvatarStatus;
+
+  /**
+   * Whether to show status indicator.
+   * @default false
+   */
+  showStatus?: boolean;
+}
+
+/**
+ * Avatar component for user representation with image, initials fallback, and status indicators.
+ *
+ * @example
+ * ```tsx
+ * // With image
+ * <Avatar src="/user.jpg" alt="John Doe" name="John Doe" />
+ *
+ * // With initials fallback
+ * <Avatar name="John Doe" />
+ *
+ * // With status indicator
+ * <Avatar name="John" status="online" showStatus />
+ * ```
+ */
+export const Avatar = forwardRef<HTMLElement, AvatarProps>(function Avatar(
+  {
+    src,
+    alt,
+    name,
+    size = "md",
+    shape = "circle",
+    status,
+    showStatus = false,
+    className,
+    ...props
+  },
+  ref
+) {
+  // Resolve responsive size - use base value for the WC attribute
+  const resolvedSize = resolveResponsiveValue(size, "md");
+  const isResponsive = isResponsiveObject(size);
+  const responsiveSizeAttr = isResponsive ? generateResponsiveDataAttr(size) : undefined;
+
+  return createElement("ds-avatar", {
+    ref,
+    src,
+    alt,
+    name,
+    size: resolvedSize,
+    shape,
+    status,
+    "show-status": showStatus || undefined,
+    class: className,
+    // Add responsive data attribute for CSS targeting
+    "data-size-responsive": responsiveSizeAttr,
+    ...props,
+  });
+});
+
+// TypeScript declaration for JSX
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      "ds-avatar": AvatarProps & {
+        ref?: React.Ref<HTMLElement>;
+        "show-status"?: boolean;
+      };
+    }
+  }
+}

package/templates/avatar/index.tsx

@@ -0,0 +1,33 @@
+"use client";
+
+/**
+ * Avatar compound component exports
+ */
+
+import { AvatarGroup } from "./avatar-group.js";
+import { Avatar as AvatarRoot } from "./avatar.js";
+
+export type { AvatarProps, AvatarSize, AvatarShape, AvatarStatus } from "./avatar.js";
+export type { AvatarGroupProps } from "./avatar-group.js";
+
+/**
+ * Avatar compound component for user representation.
+ *
+ * @example
+ * ```tsx
+ * // Single avatar
+ * <Avatar src="/user.jpg" name="John Doe" />
+ *
+ * // Avatar group
+ * <Avatar.Group max={3}>
+ *   <Avatar name="Alice" />
+ *   <Avatar name="Bob" />
+ *   <Avatar name="Charlie" />
+ * </Avatar.Group>
+ * ```
+ */
+export const Avatar = Object.assign(AvatarRoot, {
+  Group: AvatarGroup,
+});
+
+export { AvatarGroup };