@hypoth-ui/cli 0.0.1 → 0.1.0

package/templates/link/link.tsx

@@ -0,0 +1,109 @@
+import type { AnchorHTMLAttributes, ReactNode } from "react";
+import { createElement, forwardRef, useCallback, useEffect, useRef } from "react";
+import { Slot } from "../primitives/slot.js";
+import type { DsNavigateEventDetail, NavigateEventHandler } from "../types/events.js";
+import type { AsChildProps } from "../types/polymorphic.js";
+import { mergeClassNames } from "../utils/merge-props.js";
+
+export type LinkVariant = "default" | "muted" | "underline";
+
+export interface LinkProps
+  extends Omit<AnchorHTMLAttributes<HTMLAnchorElement>, "href">,
+    AsChildProps {
+  /** Target URL */
+  href: string;
+  /** Whether the link opens in a new tab */
+  external?: boolean;
+  /** Visual variant */
+  variant?: LinkVariant;
+  /** Handler for ds:navigate event. Can prevent default navigation. */
+  onNavigate?: NavigateEventHandler;
+  /** Link content */
+  children?: ReactNode;
+}
+
+/**
+ * React wrapper for ds-link Web Component.
+ * Provides type-safe props and onNavigate event handler.
+ * Supports asChild for Next.js Link integration.
+ */
+export const Link = forwardRef<HTMLElement, LinkProps>((props, forwardedRef) => {
+  const {
+    href,
+    external = false,
+    variant = "default",
+    onNavigate,
+    asChild = false,
+    children,
+    className,
+    ...rest
+  } = props;
+
+  const internalRef = useRef<HTMLElement>(null);
+
+  // Store handler in ref for stable callback reference
+  const onNavigateRef = useRef(onNavigate);
+  onNavigateRef.current = onNavigate;
+
+  // Merge refs
+  useEffect(() => {
+    if (typeof forwardedRef === "function") {
+      forwardedRef(internalRef.current);
+    } else if (forwardedRef) {
+      (forwardedRef as React.MutableRefObject<HTMLElement | null>).current = internalRef.current;
+    }
+  }, [forwardedRef]);
+
+  // Stable handler that reads from ref
+  const handleNavigate = useCallback((event: Event) => {
+    onNavigateRef.current?.(event as CustomEvent<DsNavigateEventDetail>);
+  }, []);
+
+  // Attach ds:navigate event listener - no handler deps needed
+  useEffect(() => {
+    const element = internalRef.current;
+    if (!element) return;
+
+    element.addEventListener("ds:navigate", handleNavigate);
+    return () => element.removeEventListener("ds:navigate", handleNavigate);
+  }, [handleNavigate]);
+
+  // asChild mode: render child with link styling classes
+  if (asChild) {
+    const linkClasses = mergeClassNames(
+      "ds-link",
+      `ds-link--${variant}`,
+      external && "ds-link--external",
+      className
+    );
+
+    return createElement(
+      Slot,
+      {
+        ref: internalRef,
+        className: linkClasses,
+        ...rest,
+      },
+      children
+    );
+  }
+
+  // Default mode: render ds-link Web Component
+  return createElement(
+    "ds-link",
+    {
+      ref: internalRef,
+      href,
+      external: external || undefined,
+      variant,
+      class: className,
+      ...rest,
+    },
+    children
+  );
+});
+
+Link.displayName = "Link";
+
+// Re-export event types for convenience
+export type { DsNavigateEventDetail, NavigateEventHandler };

package/templates/link/wc/link.ts

@@ -0,0 +1,124 @@
+import { type TemplateResult, html, nothing } from "lit";
+import { property } from "lit/decorators.js";
+import { classMap } from "lit/directives/class-map.js";
+import { DSElement } from "../../base/ds-element.js";
+import { StandardEvents, emitEvent } from "../../events/emit.js";
+import { define } from "../../registry/define.js";
+
+export type LinkVariant = "default" | "muted" | "underline";
+
+export interface DsNavigateEventDetail {
+  href: string;
+  external: boolean;
+  originalEvent: MouseEvent | KeyboardEvent;
+}
+
+/**
+ * A link component following WAI-ARIA link pattern.
+ *
+ * @element ds-link
+ * @slot - Default slot for link content
+ *
+ * @fires ds:navigate - When the link is activated (cancelable)
+ */
+export class DsLink extends DSElement {
+  static override styles = [];
+
+  /**
+   * The URL to navigate to.
+   * Required for proper link functionality.
+   */
+  @property({ type: String, reflect: true })
+  href = "";
+
+  /**
+   * Whether this link opens in a new tab.
+   * When true, adds target="_blank" and rel="noopener noreferrer".
+   */
+  @property({ type: Boolean, reflect: true })
+  external = false;
+
+  /**
+   * The link visual variant.
+   */
+  @property({ type: String, reflect: true })
+  variant: LinkVariant = "default";
+
+  private handleClick(event: MouseEvent): void {
+    // Emit cancelable ds:navigate event
+    const navigateEvent = emitEvent<DsNavigateEventDetail>(this, StandardEvents.NAVIGATE, {
+      detail: {
+        href: this.href,
+        external: this.external,
+        originalEvent: event,
+      },
+      cancelable: true,
+    });
+
+    // If consumer prevented the event, prevent navigation
+    if (navigateEvent.defaultPrevented) {
+      event.preventDefault();
+    }
+  }
+
+  override render(): TemplateResult {
+    const classes = {
+      "ds-link": true,
+      [`ds-link--${this.variant}`]: true,
+      "ds-link--external": this.external,
+    };
+
+    // If href is empty, render as span (not a real link)
+    if (!this.href) {
+      return html`
+        <span class=${classMap(classes)}>
+          <span class="ds-link__content"><slot></slot></span>
+        </span>
+      `;
+    }
+
+    return html`
+      <a
+        class=${classMap(classes)}
+        href=${this.href}
+        target=${this.external ? "_blank" : nothing}
+        rel=${this.external ? "noopener noreferrer" : nothing}
+        @click=${this.handleClick}
+      >
+        <span class="ds-link__content"><slot></slot></span>
+        ${this.external ? this.renderExternalIndicator() : nothing}
+      </a>
+    `;
+  }
+
+  private renderExternalIndicator(): TemplateResult {
+    return html`
+      <span class="ds-link__external-icon" aria-hidden="true">
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+        >
+          <path d="M18 13v6a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2V8a2 2 0 0 1 2-2h6" />
+          <polyline points="15 3 21 3 21 9" />
+          <line x1="10" y1="14" x2="21" y2="3" />
+        </svg>
+      </span>
+      <span class="ds-visually-hidden">(opens in new tab)</span>
+    `;
+  }
+}
+
+// Register the component
+define("ds-link", DsLink);
+
+// TypeScript declaration for HTML
+declare global {
+  interface HTMLElementTagNameMap {
+    "ds-link": DsLink;
+  }
+}

package/templates/list/index.tsx

@@ -0,0 +1,55 @@
+"use client";
+
+/**
+ * List compound component exports
+ */
+
+import { ListItem } from "./list-item.js";
+import { ListRoot } from "./list.js";
+
+export type { ListRootProps, ListSelectionMode, ListOrientation, ListSize } from "./list.js";
+export type { ListItemProps } from "./list-item.js";
+
+/**
+ * List compound component for collection display.
+ *
+ * @example
+ * ```tsx
+ * <List selectionMode="single" onSelectionChange={(ids) => console.log(ids)}>
+ *   <List.Item itemId="1">Item 1</List.Item>
+ *   <List.Item itemId="2">Item 2</List.Item>
+ *   <List.Item itemId="3" disabled>Item 3 (disabled)</List.Item>
+ * </List>
+ * ```
+ */
+export const List = Object.assign(ListRoot, {
+  Item: ListItem,
+});
+
+export { ListItem };
+
+// TypeScript declarations for JSX
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      "ds-list": React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
+        ref?: React.Ref<HTMLElement>;
+        "selection-mode"?: string;
+        orientation?: string;
+        size?: string;
+        bordered?: boolean;
+        label?: string;
+        "onDs-selection-change"?: (event: CustomEvent) => void;
+      };
+      "ds-list-item": React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
+        ref?: React.Ref<HTMLElement>;
+        "item-id"?: string;
+        selected?: boolean;
+        disabled?: boolean;
+        value?: string;
+        "onDs-select"?: (event: CustomEvent) => void;
+        "onDs-activate"?: (event: CustomEvent) => void;
+      };
+    }
+  }
+}

package/templates/list/list-item.tsx

@@ -0,0 +1,117 @@
+"use client";
+
+import {
+  type HTMLAttributes,
+  type ReactNode,
+  createElement,
+  forwardRef,
+  useEffect,
+  useRef,
+} from "react";
+import "@hypoth-ui/wc";
+
+export interface ListItemProps extends Omit<HTMLAttributes<HTMLElement>, "onSelect"> {
+  /**
+   * Unique item ID.
+   */
+  itemId?: string;
+
+  /**
+   * Whether item is selected.
+   * @default false
+   */
+  selected?: boolean;
+
+  /**
+   * Whether item is disabled.
+   * @default false
+   */
+  disabled?: boolean;
+
+  /**
+   * Value for identification.
+   */
+  value?: string;
+
+  /**
+   * Callback when item is selected.
+   */
+  onItemSelect?: (itemId: string, value: string, selected: boolean) => void;
+
+  /**
+   * Callback when item is activated (Enter/double-click).
+   */
+  onActivate?: (itemId: string, value: string) => void;
+
+  /**
+   * Item content.
+   */
+  children?: ReactNode;
+}
+
+/**
+ * List item component for collection items.
+ */
+export const ListItem = forwardRef<HTMLElement, ListItemProps>(function ListItem(
+  {
+    itemId,
+    selected = false,
+    disabled = false,
+    value,
+    onItemSelect,
+    onActivate,
+    children,
+    className,
+    ...props
+  },
+  forwardedRef
+) {
+  const internalRef = useRef<HTMLElement>(null);
+
+  // Sync forwarded ref
+  useEffect(() => {
+    if (typeof forwardedRef === "function") {
+      forwardedRef(internalRef.current);
+    } else if (forwardedRef) {
+      (forwardedRef as React.MutableRefObject<HTMLElement | null>).current = internalRef.current;
+    }
+  }, [forwardedRef]);
+
+  // Set up event listeners
+  useEffect(() => {
+    const element = internalRef.current;
+    if (!element) return;
+
+    const handleSelect = (e: Event) => {
+      const event = e as CustomEvent<{ itemId: string; value: string; selected: boolean }>;
+      onItemSelect?.(event.detail.itemId, event.detail.value, event.detail.selected);
+    };
+
+    const handleActivate = (e: Event) => {
+      const event = e as CustomEvent<{ itemId: string; value: string }>;
+      onActivate?.(event.detail.itemId, event.detail.value);
+    };
+
+    element.addEventListener("ds:select", handleSelect);
+    element.addEventListener("ds:activate", handleActivate);
+
+    return () => {
+      element.removeEventListener("ds:select", handleSelect);
+      element.removeEventListener("ds:activate", handleActivate);
+    };
+  }, [onItemSelect, onActivate]);
+
+  return createElement(
+    "ds-list-item",
+    {
+      ref: internalRef,
+      "item-id": itemId,
+      selected: selected || undefined,
+      disabled: disabled || undefined,
+      value,
+      class: className,
+      ...props,
+    },
+    children
+  );
+});

package/templates/list/list.tsx

@@ -0,0 +1,115 @@
+"use client";
+
+import {
+  type HTMLAttributes,
+  type ReactNode,
+  createElement,
+  forwardRef,
+  useEffect,
+  useRef,
+} from "react";
+import "@hypoth-ui/wc";
+
+export type ListSelectionMode = "single" | "multiple" | "none";
+export type ListOrientation = "vertical" | "horizontal";
+export type ListSize = "default" | "compact" | "spacious";
+
+export interface ListRootProps extends HTMLAttributes<HTMLElement> {
+  /**
+   * Selection mode.
+   * @default "single"
+   */
+  selectionMode?: ListSelectionMode;
+
+  /**
+   * List orientation.
+   * @default "vertical"
+   */
+  orientation?: ListOrientation;
+
+  /**
+   * Size variant.
+   * @default "default"
+   */
+  size?: ListSize;
+
+  /**
+   * Show border around list.
+   * @default false
+   */
+  bordered?: boolean;
+
+  /**
+   * Accessible label.
+   * @default "List"
+   */
+  label?: string;
+
+  /**
+   * Callback when selection changes.
+   */
+  onSelectionChange?: (selectedItems: string[]) => void;
+
+  /**
+   * List content (ListItem elements).
+   */
+  children?: ReactNode;
+}
+
+/**
+ * List root component for collection display.
+ */
+export const ListRoot = forwardRef<HTMLElement, ListRootProps>(function ListRoot(
+  {
+    selectionMode = "single",
+    orientation = "vertical",
+    size = "default",
+    bordered = false,
+    label = "List",
+    onSelectionChange,
+    children,
+    className,
+    ...props
+  },
+  forwardedRef
+) {
+  const internalRef = useRef<HTMLElement>(null);
+
+  // Sync forwarded ref
+  useEffect(() => {
+    if (typeof forwardedRef === "function") {
+      forwardedRef(internalRef.current);
+    } else if (forwardedRef) {
+      (forwardedRef as React.MutableRefObject<HTMLElement | null>).current = internalRef.current;
+    }
+  }, [forwardedRef]);
+
+  // Set up event listeners
+  useEffect(() => {
+    const element = internalRef.current;
+    if (!element) return;
+
+    const handleSelectionChange = (e: Event) => {
+      const event = e as CustomEvent<{ selectedItems: string[] }>;
+      onSelectionChange?.(event.detail.selectedItems);
+    };
+
+    element.addEventListener("ds:selection-change", handleSelectionChange);
+    return () => element.removeEventListener("ds:selection-change", handleSelectionChange);
+  }, [onSelectionChange]);
+
+  return createElement(
+    "ds-list",
+    {
+      ref: internalRef,
+      "selection-mode": selectionMode,
+      orientation,
+      size,
+      bordered: bordered || undefined,
+      label,
+      class: className,
+      ...props,
+    },
+    children
+  );
+});

package/templates/list/wc/index.ts

@@ -0,0 +1,5 @@
+/**
+ * List component exports
+ */
+export { DsList, type ListSelectionMode, type ListOrientation, type ListSize } from "./list.js";
+export { DsListItem } from "./list-item.js";

package/templates/list/wc/list-item.ts

@@ -0,0 +1,127 @@
+import { type TemplateResult, html, nothing } from "lit";
+import { property } 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";
+import type { DsList } from "./list.js";
+
+/**
+ * List item component for collection items.
+ *
+ * @element ds-list-item
+ *
+ * @slot - Item content
+ * @slot leading - Optional leading element (icon, avatar)
+ * @slot secondary - Optional secondary text
+ * @slot trailing - Optional trailing element (action, badge)
+ *
+ * @fires ds-select - When item is selected
+ * @fires ds-activate - When item is activated (Enter/double-click)
+ */
+export class DsListItem extends DSElement {
+  static override styles = [];
+
+  /**
+   * Unique item ID.
+   */
+  @property({ type: String, attribute: "item-id" })
+  itemId = "";
+
+  /**
+   * Whether item is selected.
+   */
+  @property({ type: Boolean, reflect: true })
+  selected = false;
+
+  /**
+   * Whether item is disabled.
+   */
+  @property({ type: Boolean, reflect: true })
+  disabled = false;
+
+  /**
+   * Value for identification.
+   */
+  @property({ type: String })
+  value = "";
+
+  private get listRoot(): DsList | null {
+    return this.closest("ds-list") as DsList | null;
+  }
+
+  private handleClick(): void {
+    if (this.disabled) return;
+
+    const list = this.listRoot;
+    if (list) {
+      list.handleItemSelect(this.itemId || this.value);
+      this.selected = list.isItemSelected(this.itemId || this.value);
+    }
+
+    emitEvent(this, "select", {
+      detail: {
+        itemId: this.itemId,
+        value: this.value,
+        selected: this.selected,
+      },
+    });
+  }
+
+  private handleKeyDown(event: KeyboardEvent): void {
+    if (this.disabled) return;
+
+    if (event.key === "Enter" || event.key === " ") {
+      event.preventDefault();
+      this.handleClick();
+
+      if (event.key === "Enter") {
+        emitEvent(this, "activate", {
+          detail: {
+            itemId: this.itemId,
+            value: this.value,
+          },
+        });
+      }
+    }
+  }
+
+  override render(): TemplateResult {
+    const classes = {
+      "ds-list-item": true,
+    };
+
+    return html`
+      <li
+        class=${classMap(classes)}
+        role="option"
+        tabindex=${this.disabled ? -1 : 0}
+        aria-selected=${this.selected ? "true" : "false"}
+        ?data-selected=${this.selected}
+        ?data-disabled=${this.disabled}
+        aria-disabled=${this.disabled ? "true" : nothing}
+        @click=${this.handleClick}
+        @keydown=${this.handleKeyDown}
+      >
+        <slot name="leading"></slot>
+        <div class="ds-list-item__content">
+          <span class="ds-list-item__primary">
+            <slot></slot>
+          </span>
+          <slot name="secondary"></slot>
+        </div>
+        <slot name="trailing"></slot>
+      </li>
+    `;
+  }
+}
+
+// Register the component
+define("ds-list-item", DsListItem);
+
+// TypeScript declaration for HTML
+declare global {
+  interface HTMLElementTagNameMap {
+    "ds-list-item": DsListItem;
+  }
+}