@hypoth-ui/cli 0.0.1 → 0.1.0

package/templates/list/wc/list.ts

@@ -0,0 +1,114 @@
+import { type TemplateResult, html, nothing } from "lit";
+import { property, state } from "lit/decorators.js";
+import { classMap } from "lit/directives/class-map.js";
+import { DSElement } from "../../base/ds-element.js";
+import { emitEvent } from "../../events/emit.js";
+import { define } from "../../registry/define.js";
+
+export type ListSelectionMode = "single" | "multiple" | "none";
+export type ListOrientation = "vertical" | "horizontal";
+export type ListSize = "default" | "compact" | "spacious";
+
+/**
+ * List root component for collection display.
+ *
+ * @element ds-list
+ *
+ * @slot - ListItem elements
+ *
+ * @fires ds-selection-change - When selection changes
+ *
+ * @cssprop --ds-list-gap - Gap between items
+ */
+export class DsList extends DSElement {
+  static override styles = [];
+
+  /**
+   * Selection mode.
+   */
+  @property({ type: String, attribute: "selection-mode", reflect: true })
+  selectionMode: ListSelectionMode = "single";
+
+  /**
+   * List orientation.
+   */
+  @property({ type: String, reflect: true })
+  orientation: ListOrientation = "vertical";
+
+  /**
+   * Size variant.
+   */
+  @property({ type: String, reflect: true })
+  size: ListSize = "default";
+
+  /**
+   * Show border around list.
+   */
+  @property({ type: Boolean, reflect: true })
+  bordered = false;
+
+  /**
+   * Accessible label.
+   */
+  @property({ type: String })
+  label = "List";
+
+  @state()
+  private selectedItems: Set<string> = new Set();
+
+  handleItemSelect(itemId: string): void {
+    if (this.selectionMode === "none") return;
+
+    if (this.selectionMode === "single") {
+      this.selectedItems.clear();
+      this.selectedItems.add(itemId);
+    } else {
+      if (this.selectedItems.has(itemId)) {
+        this.selectedItems.delete(itemId);
+      } else {
+        this.selectedItems.add(itemId);
+      }
+    }
+
+    emitEvent(this, "selection-change", {
+      detail: { selectedItems: Array.from(this.selectedItems) },
+    });
+
+    this.requestUpdate();
+  }
+
+  isItemSelected(itemId: string): boolean {
+    return this.selectedItems.has(itemId);
+  }
+
+  override render(): TemplateResult {
+    const classes = {
+      "ds-list": true,
+    };
+
+    return html`
+      <ul
+        class=${classMap(classes)}
+        role="listbox"
+        aria-label=${this.label}
+        aria-multiselectable=${this.selectionMode === "multiple" ? "true" : nothing}
+        aria-orientation=${this.orientation}
+        data-size=${this.size !== "default" ? this.size : nothing}
+        data-orientation=${this.orientation !== "vertical" ? this.orientation : nothing}
+        ?data-bordered=${this.bordered}
+      >
+        <slot></slot>
+      </ul>
+    `;
+  }
+}
+
+// Register the component
+define("ds-list", DsList);
+
+// TypeScript declaration for HTML
+declare global {
+  interface HTMLElementTagNameMap {
+    "ds-list": DsList;
+  }
+}

package/templates/menu/index.ts

@@ -0,0 +1,49 @@
+/**
+ * Menu compound component exports.
+ *
+ * @example
+ * ```tsx
+ * import { Menu } from "@/components/ui";
+ *
+ * <Menu.Root onSelect={(value) => console.log(value)}>
+ *   <Menu.Trigger>Actions</Menu.Trigger>
+ *   <Menu.Content>
+ *     <Menu.Label>Options</Menu.Label>
+ *     <Menu.Item value="edit">Edit</Menu.Item>
+ *     <Menu.Item value="duplicate">Duplicate</Menu.Item>
+ *     <Menu.Separator />
+ *     <Menu.Item value="delete">Delete</Menu.Item>
+ *   </Menu.Content>
+ * </Menu.Root>
+ * ```
+ */
+
+import { MenuContent, type MenuContentProps } from "./menu-content.js";
+import { MenuItem, type MenuItemProps } from "./menu-item.js";
+import { MenuLabel, type MenuLabelProps } from "./menu-label.js";
+import { MenuRoot, type MenuRootProps } from "./menu-root.js";
+import { MenuSeparator, type MenuSeparatorProps } from "./menu-separator.js";
+import { MenuTrigger, type MenuTriggerProps } from "./menu-trigger.js";
+
+// Compound component
+export const Menu = {
+  Root: MenuRoot,
+  Trigger: MenuTrigger,
+  Content: MenuContent,
+  Item: MenuItem,
+  Separator: MenuSeparator,
+  Label: MenuLabel,
+};
+
+// Type exports
+export type {
+  MenuContentProps,
+  MenuItemProps,
+  MenuLabelProps,
+  MenuRootProps,
+  MenuSeparatorProps,
+  MenuTriggerProps,
+};
+
+// Re-export Placement from primitives-dom
+export type { Placement } from "@hypoth-ui/primitives-dom";

package/templates/menu/menu-content.tsx

@@ -0,0 +1,109 @@
+/**
+ * Menu Content component - the menu panel with items.
+ */
+
+import {
+  type HTMLAttributes,
+  type ReactNode,
+  forwardRef,
+  useCallback,
+  useEffect,
+  useRef,
+} from "react";
+import { createPortal } from "react-dom";
+import { useMenuContext } from "./menu-context.js";
+
+export interface MenuContentProps extends HTMLAttributes<HTMLDivElement> {
+  /** Menu content */
+  children?: ReactNode;
+  /** Container element for portal (defaults to document.body) */
+  container?: HTMLElement | null;
+  /** Force mount even when closed (for animations) */
+  forceMount?: boolean;
+}
+
+/**
+ * Menu content panel with roving focus and type-ahead.
+ * Renders in a portal by default.
+ *
+ * @example
+ * ```tsx
+ * <Menu.Content>
+ *   <Menu.Item value="edit">Edit</Menu.Item>
+ *   <Menu.Item value="delete">Delete</Menu.Item>
+ * </Menu.Content>
+ * ```
+ */
+export const MenuContent = forwardRef<HTMLDivElement, MenuContentProps>(
+  ({ children, container, forceMount = false, onKeyDown, ...restProps }, ref) => {
+    const { behavior, open } = useMenuContext("Menu.Content");
+    const internalRef = useRef<HTMLDivElement>(null);
+
+    // Register content element with behavior
+    useEffect(() => {
+      if (open) {
+        const element = internalRef.current;
+        behavior.setContentElement(element);
+        return () => {
+          behavior.setContentElement(null);
+        };
+      }
+    }, [behavior, open]);
+
+    // Handle keyboard events
+    const handleKeyDown = useCallback(
+      (event: React.KeyboardEvent<HTMLDivElement>) => {
+        behavior.handleContentKeyDown(event.nativeEvent);
+        onKeyDown?.(event);
+      },
+      [behavior, onKeyDown]
+    );
+
+    // Get content props from behavior
+    const contentProps = behavior.getContentProps();
+
+    // Merge refs
+    const mergedRef = useCallback(
+      (element: HTMLDivElement | null) => {
+        (internalRef as React.MutableRefObject<HTMLDivElement | null>).current = element;
+        if (typeof ref === "function") {
+          ref(element);
+        } else if (ref) {
+          (ref as React.MutableRefObject<HTMLDivElement | null>).current = element;
+        }
+      },
+      [ref]
+    );
+
+    // Don't render if closed and not force mounted
+    if (!open && !forceMount) {
+      return null;
+    }
+
+    const content = (
+      <div
+        ref={mergedRef}
+        id={contentProps.id}
+        role={contentProps.role}
+        aria-labelledby={contentProps["aria-labelledby"]}
+        aria-orientation={contentProps["aria-orientation"]}
+        tabIndex={contentProps.tabIndex}
+        data-state={open ? "open" : "closed"}
+        onKeyDown={handleKeyDown}
+        {...restProps}
+      >
+        {children}
+      </div>
+    );
+
+    // Render in portal
+    const portalContainer = container ?? (typeof document !== "undefined" ? document.body : null);
+    if (portalContainer) {
+      return createPortal(content, portalContainer);
+    }
+
+    return content;
+  }
+);
+
+MenuContent.displayName = "Menu.Content";

package/templates/menu/menu-context.ts

@@ -0,0 +1,17 @@
+/**
+ * Menu context for compound component pattern.
+ */
+
+import type { MenuBehavior } from "@hypoth-ui/primitives-dom";
+import { createCompoundContext } from "../../utils/create-context.js";
+
+export interface MenuContextValue {
+  /** Menu behavior instance */
+  behavior: MenuBehavior;
+  /** Whether menu is open */
+  open: boolean;
+  /** Set open state */
+  setOpen: (open: boolean) => void;
+}
+
+export const [MenuProvider, useMenuContext] = createCompoundContext<MenuContextValue>("Menu");

package/templates/menu/menu-item.tsx

@@ -0,0 +1,108 @@
+/**
+ * Menu Item component - a selectable item in the menu.
+ */
+
+import {
+  type HTMLAttributes,
+  type ReactNode,
+  forwardRef,
+  useCallback,
+  useEffect,
+  useRef,
+} from "react";
+import { useMenuContext } from "./menu-context.js";
+
+export interface MenuItemProps extends HTMLAttributes<HTMLDivElement> {
+  /** Item content */
+  children?: ReactNode;
+  /** Value passed to onSelect */
+  value?: string;
+  /** Whether item is disabled */
+  disabled?: boolean;
+}
+
+/**
+ * A selectable item in the menu.
+ *
+ * @example
+ * ```tsx
+ * <Menu.Item value="edit">Edit</Menu.Item>
+ * <Menu.Item value="delete" disabled>Delete</Menu.Item>
+ * ```
+ */
+export const MenuItem = forwardRef<HTMLDivElement, MenuItemProps>(
+  ({ children, value = "", disabled = false, onClick, onPointerEnter, ...restProps }, ref) => {
+    const { behavior } = useMenuContext("Menu.Item");
+    const internalRef = useRef<HTMLDivElement>(null);
+    const indexRef = useRef<number>(-1);
+
+    // Register item with behavior
+    useEffect(() => {
+      const element = internalRef.current;
+      if (element) {
+        behavior.registerItem(element);
+        // Get index after registration
+        indexRef.current = behavior.context.items.indexOf(element);
+        return () => {
+          behavior.unregisterItem(element);
+        };
+      }
+    }, [behavior]);
+
+    // Handle click
+    const handleClick = useCallback(
+      (event: React.MouseEvent<HTMLDivElement>) => {
+        if (!disabled) {
+          behavior.handleItemClick(indexRef.current, value);
+        }
+        onClick?.(event);
+      },
+      [behavior, disabled, value, onClick]
+    );
+
+    // Handle pointer enter (hover)
+    const handlePointerEnter = useCallback(
+      (event: React.PointerEvent<HTMLDivElement>) => {
+        if (!disabled) {
+          behavior.handleItemPointerEnter(indexRef.current);
+        }
+        onPointerEnter?.(event);
+      },
+      [behavior, disabled, onPointerEnter]
+    );
+
+    // Get item props from behavior (need index)
+    const itemProps = behavior.getItemProps(indexRef.current, { disabled });
+
+    // Merge refs
+    const mergedRef = useCallback(
+      (element: HTMLDivElement | null) => {
+        (internalRef as React.MutableRefObject<HTMLDivElement | null>).current = element;
+        if (typeof ref === "function") {
+          ref(element);
+        } else if (ref) {
+          (ref as React.MutableRefObject<HTMLDivElement | null>).current = element;
+        }
+      },
+      [ref]
+    );
+
+    return (
+      <div
+        ref={mergedRef}
+        role={itemProps.role}
+        tabIndex={itemProps.tabIndex}
+        aria-disabled={itemProps["aria-disabled"]}
+        data-highlighted={itemProps["data-highlighted"]}
+        data-value={value}
+        onClick={handleClick}
+        onPointerEnter={handlePointerEnter}
+        {...restProps}
+      >
+        {children}
+      </div>
+    );
+  }
+);
+
+MenuItem.displayName = "Menu.Item";

package/templates/menu/menu-label.tsx

@@ -0,0 +1,32 @@
+/**
+ * Menu Label component - non-interactive label for a group of items.
+ */
+
+import { type HTMLAttributes, type ReactNode, forwardRef } from "react";
+
+export interface MenuLabelProps extends HTMLAttributes<HTMLDivElement> {
+  /** Label content */
+  children?: ReactNode;
+}
+
+/**
+ * Non-interactive label for a group of menu items.
+ *
+ * @example
+ * ```tsx
+ * <Menu.Label>Actions</Menu.Label>
+ * <Menu.Item value="edit">Edit</Menu.Item>
+ * <Menu.Item value="delete">Delete</Menu.Item>
+ * ```
+ */
+export const MenuLabel = forwardRef<HTMLDivElement, MenuLabelProps>(
+  ({ children, ...restProps }, ref) => {
+    return (
+      <div ref={ref} role="presentation" {...restProps}>
+        {children}
+      </div>
+    );
+  }
+);
+
+MenuLabel.displayName = "Menu.Label";

package/templates/menu/menu-root.tsx

@@ -0,0 +1,108 @@
+/**
+ * Menu Root component - provides context to all Menu compound components.
+ */
+
+import { type Placement, createMenuBehavior } from "@hypoth-ui/primitives-dom";
+import { type ReactNode, useCallback, useMemo, useState } from "react";
+import { useStableId } from "../../hooks/use-stable-id.js";
+import { MenuProvider } from "./menu-context.js";
+
+export interface MenuRootProps {
+  /** Menu content */
+  children?: ReactNode;
+  /** Custom ID for the menu (SSR-safe auto-generated if not provided) */
+  id?: string;
+  /** Controlled open state */
+  open?: boolean;
+  /** Default open state (uncontrolled) */
+  defaultOpen?: boolean;
+  /** Called when open state changes */
+  onOpenChange?: (open: boolean) => void;
+  /** Called when an item is selected */
+  onSelect?: (value: string) => void;
+  /** Placement relative to trigger */
+  placement?: Placement;
+  /** Offset from trigger in pixels */
+  offset?: number;
+  /** Whether to flip placement on viewport edge */
+  flip?: boolean;
+  /** Whether to loop navigation at ends */
+  loop?: boolean;
+}
+
+/**
+ * Root component for Menu compound pattern.
+ * Provides context to Trigger, Content, and Item.
+ *
+ * @example
+ * ```tsx
+ * <Menu.Root onSelect={(value) => console.log(value)}>
+ *   <Menu.Trigger>Open Menu</Menu.Trigger>
+ *   <Menu.Content>
+ *     <Menu.Item value="edit">Edit</Menu.Item>
+ *     <Menu.Item value="delete">Delete</Menu.Item>
+ *   </Menu.Content>
+ * </Menu.Root>
+ * ```
+ */
+export function MenuRoot({
+  children,
+  id,
+  open: controlledOpen,
+  defaultOpen = false,
+  onOpenChange,
+  onSelect,
+  placement = "bottom-start",
+  offset = 4,
+  flip = true,
+  loop = true,
+}: MenuRootProps) {
+  // Generate SSR-safe stable ID using React 18's useId under the hood
+  const stableId = useStableId({ id, prefix: "menu" });
+
+  // Support both controlled and uncontrolled modes
+  const [internalOpen, setInternalOpen] = useState(defaultOpen);
+  const isControlled = controlledOpen !== undefined;
+  const open = isControlled ? controlledOpen : internalOpen;
+
+  const setOpen = useCallback(
+    (nextOpen: boolean) => {
+      if (!isControlled) {
+        setInternalOpen(nextOpen);
+      }
+      onOpenChange?.(nextOpen);
+    },
+    [isControlled, onOpenChange]
+  );
+
+  // Create behavior instance - intentionally created once with initial values
+  // biome-ignore lint/correctness/useExhaustiveDependencies: behavior is created once, open state synced via setOpen callback
+  const behavior = useMemo(
+    () =>
+      createMenuBehavior({
+        defaultOpen: open,
+        placement,
+        offset,
+        flip,
+        loop,
+        onOpenChange: setOpen,
+        onSelect,
+        // Use SSR-safe stable ID generator
+        generateId: () => stableId,
+      }),
+    [stableId]
+  );
+
+  const contextValue = useMemo(
+    () => ({
+      behavior,
+      open,
+      setOpen,
+    }),
+    [behavior, open, setOpen]
+  );
+
+  return <MenuProvider value={contextValue}>{children}</MenuProvider>;
+}
+
+MenuRoot.displayName = "Menu.Root";

package/templates/menu/menu-separator.tsx

@@ -0,0 +1,24 @@
+/**
+ * Menu Separator component - visual separator between items.
+ */
+
+import { type HTMLAttributes, forwardRef } from "react";
+
+export interface MenuSeparatorProps extends HTMLAttributes<HTMLDivElement> {}
+
+/**
+ * Visual separator between menu items.
+ *
+ * @example
+ * ```tsx
+ * <Menu.Item value="edit">Edit</Menu.Item>
+ * <Menu.Separator />
+ * <Menu.Item value="delete">Delete</Menu.Item>
+ * ```
+ */
+export const MenuSeparator = forwardRef<HTMLDivElement, MenuSeparatorProps>((props, ref) => {
+  // biome-ignore lint/a11y/useFocusableInteractive: separator is decorative, not interactive
+  return <div ref={ref} role="separator" aria-orientation="horizontal" {...props} />;
+});
+
+MenuSeparator.displayName = "Menu.Separator";

package/templates/menu/menu-trigger.tsx

@@ -0,0 +1,104 @@
+/**
+ * Menu Trigger component - opens the menu when activated.
+ */
+
+import {
+  type ButtonHTMLAttributes,
+  type ReactNode,
+  forwardRef,
+  useCallback,
+  useEffect,
+  useRef,
+} from "react";
+import { Slot } from "../../primitives/slot.js";
+import { useMenuContext } from "./menu-context.js";
+
+export interface MenuTriggerProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  /** Trigger content */
+  children?: ReactNode;
+  /** Render as child element (polymorphic) */
+  asChild?: boolean;
+}
+
+/**
+ * Trigger button that opens the menu.
+ * Supports asChild for custom trigger elements.
+ *
+ * @example
+ * ```tsx
+ * <Menu.Trigger>Open Menu</Menu.Trigger>
+ *
+ * <Menu.Trigger asChild>
+ *   <button className="custom-button">Custom Trigger</button>
+ * </Menu.Trigger>
+ * ```
+ */
+export const MenuTrigger = forwardRef<HTMLButtonElement, MenuTriggerProps>(
+  ({ children, asChild = false, onClick, onKeyDown, ...restProps }, ref) => {
+    const { behavior } = useMenuContext("Menu.Trigger");
+    const internalRef = useRef<HTMLButtonElement>(null);
+
+    // Register trigger element with behavior
+    useEffect(() => {
+      const element = internalRef.current;
+      behavior.setTriggerElement(element);
+      return () => {
+        behavior.setTriggerElement(null);
+      };
+    }, [behavior]);
+
+    // Handle click to toggle menu
+    const handleClick = useCallback(
+      (event: React.MouseEvent<HTMLButtonElement>) => {
+        behavior.toggle();
+        onClick?.(event);
+      },
+      [behavior, onClick]
+    );
+
+    // Handle keyboard navigation
+    const handleKeyDown = useCallback(
+      (event: React.KeyboardEvent<HTMLButtonElement>) => {
+        behavior.handleTriggerKeyDown(event.nativeEvent);
+        onKeyDown?.(event);
+      },
+      [behavior, onKeyDown]
+    );
+
+    // Get trigger props from behavior
+    const triggerProps = behavior.getTriggerProps();
+
+    const Component = asChild ? Slot : "button";
+
+    // Merge refs
+    const mergedRef = useCallback(
+      (element: HTMLButtonElement | null) => {
+        (internalRef as React.MutableRefObject<HTMLButtonElement | null>).current = element;
+        if (typeof ref === "function") {
+          ref(element);
+        } else if (ref) {
+          (ref as React.MutableRefObject<HTMLButtonElement | null>).current = element;
+        }
+      },
+      [ref]
+    );
+
+    return (
+      <Component
+        ref={mergedRef}
+        type={asChild ? undefined : "button"}
+        id={triggerProps.id}
+        aria-haspopup={triggerProps["aria-haspopup"]}
+        aria-expanded={triggerProps["aria-expanded"]}
+        aria-controls={triggerProps["aria-controls"]}
+        onClick={handleClick}
+        onKeyDown={handleKeyDown}
+        {...restProps}
+      >
+        {children}
+      </Component>
+    );
+  }
+);
+
+MenuTrigger.displayName = "Menu.Trigger";