@hypoth-ui/cli 0.0.1 → 0.1.0

package/templates/icon/icon.tsx

@@ -0,0 +1,76 @@
+import { createElement, forwardRef, useEffect, useRef } from "react";
+import {
+  type ResponsiveProp,
+  generateResponsiveDataAttr,
+  isResponsiveObject,
+  resolveResponsiveValue,
+} from "../primitives/responsive.js";
+
+export type IconSize = "xs" | "sm" | "md" | "lg" | "xl";
+
+/**
+ * Icon name from Lucide library (kebab-case format).
+ * This is a nominal type alias to document the expected format.
+ */
+export type IconName = string;
+
+export interface IconProps {
+  /** Icon name from Lucide library (kebab-case) */
+  name: string;
+  /**
+   * Icon size - supports responsive object syntax
+   * @example
+   * ```tsx
+   * // Single value
+   * <Icon name="check" size="md" />
+   *
+   * // Responsive
+   * <Icon name="check" size={{ base: "sm", md: "md", lg: "lg" }} />
+   * ```
+   */
+  size?: ResponsiveProp<IconSize>;
+  /** Accessible label. When omitted, icon is decorative. */
+  label?: string;
+  /** Custom color (CSS value) */
+  color?: string;
+  /** Additional CSS classes */
+  className?: string;
+}
+
+/**
+ * React wrapper for ds-icon Web Component.
+ * Provides type-safe props for icon display.
+ */
+export const Icon = forwardRef<HTMLElement, IconProps>((props, forwardedRef) => {
+  const { name, size = "md", label, color, className, ...rest } = props;
+
+  const internalRef = useRef<HTMLElement>(null);
+
+  // Merge refs
+  useEffect(() => {
+    if (typeof forwardedRef === "function") {
+      forwardedRef(internalRef.current);
+    } else if (forwardedRef) {
+      (forwardedRef as React.MutableRefObject<HTMLElement | null>).current = internalRef.current;
+    }
+  }, [forwardedRef]);
+
+  // 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-icon", {
+    ref: internalRef,
+    name,
+    size: resolvedSize,
+    label: label || undefined,
+    color: color || undefined,
+    class: className,
+    // Add responsive data attribute for CSS targeting
+    "data-size-responsive": responsiveSizeAttr,
+    ...rest,
+  });
+});
+
+Icon.displayName = "Icon";

package/templates/icon/wc/icon-adapter.ts

@@ -0,0 +1,108 @@
+/**
+ * Icon Adapter for Lucide Icons
+ *
+ * Provides a unified interface for accessing icons from the Lucide library.
+ * Uses createElement() for efficient SVG generation.
+ */
+
+import { createElement, icons } from "lucide";
+import type { IconNode } from "lucide";
+
+/**
+ * Convert kebab-case to PascalCase for Lucide icon names
+ * e.g., "arrow-right" -> "ArrowRight"
+ */
+function toPascalCase(str: string): string {
+  return str
+    .split("-")
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1).toLowerCase())
+    .join("");
+}
+
+/**
+ * Get an SVG element for the specified icon name.
+ *
+ * @param name - The icon name in kebab-case (e.g., "arrow-right", "search", "external-link")
+ * @param options - Optional attributes to apply to the SVG
+ * @returns SVGSVGElement or null if icon not found
+ *
+ * @example
+ * ```typescript
+ * const svg = getIconSvg("search");
+ * if (svg) {
+ *   container.appendChild(svg);
+ * }
+ * ```
+ */
+export function getIconSvg(
+  name: string,
+  options?: {
+    size?: number | string;
+    color?: string;
+    strokeWidth?: number | string;
+  }
+): SVGSVGElement | null {
+  // Convert kebab-case name to PascalCase for Lucide lookup
+  const pascalName = toPascalCase(name);
+
+  // Check if icon exists in Lucide
+  const iconNode = icons[pascalName as keyof typeof icons] as IconNode | undefined;
+
+  if (!iconNode) {
+    if (process.env.NODE_ENV !== "production") {
+      console.warn(`[ds-icon] Icon "${name}" not found in Lucide library.`);
+    }
+    return null;
+  }
+
+  // Build custom attributes to merge with default icon attrs
+  const customAttrs: Record<string, string | number> = {};
+
+  if (options?.size) {
+    customAttrs.width = options.size;
+    customAttrs.height = options.size;
+  }
+
+  if (options?.color) {
+    customAttrs.color = options.color;
+  }
+
+  if (options?.strokeWidth) {
+    customAttrs["stroke-width"] = options.strokeWidth;
+  }
+
+  // Merge custom attributes with the icon's default attributes
+  // IconNode is [tag, attrs, children?]
+  const [tag, defaultAttrs, children] = iconNode;
+  const mergedAttrs = { ...defaultAttrs, ...customAttrs };
+  const modifiedIconNode: IconNode = children ? [tag, mergedAttrs, children] : [tag, mergedAttrs];
+
+  const element = createElement(modifiedIconNode);
+
+  return element as SVGSVGElement;
+}
+
+/**
+ * Check if an icon name exists in the Lucide library.
+ *
+ * @param name - The icon name in kebab-case
+ * @returns True if the icon exists
+ */
+export function hasIcon(name: string): boolean {
+  const pascalName = toPascalCase(name);
+  return pascalName in icons;
+}
+
+/**
+ * Get all available icon names.
+ *
+ * @returns Array of icon names in kebab-case
+ */
+export function getAvailableIcons(): string[] {
+  return Object.keys(icons).map((name) =>
+    name
+      .replace(/([A-Z])/g, "-$1")
+      .toLowerCase()
+      .replace(/^-/, "")
+  );
+}

package/templates/icon/wc/icon.ts

@@ -0,0 +1,161 @@
+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 { define } from "../../registry/define.js";
+import { getIconSvg, hasIcon } from "./icon-adapter.js";
+
+export type IconSize = "xs" | "sm" | "md" | "lg" | "xl";
+
+/**
+ * Size mappings in pixels for SVG generation
+ */
+const SIZE_MAP: Record<IconSize, number> = {
+  xs: 12,
+  sm: 16,
+  md: 20,
+  lg: 24,
+  xl: 32,
+};
+
+/**
+ * An accessible icon component with Lucide integration.
+ *
+ * @element ds-icon
+ *
+ * @example
+ * ```html
+ * <!-- Decorative icon (hidden from screen readers) -->
+ * <ds-icon name="search"></ds-icon>
+ *
+ * <!-- Meaningful icon (announced to screen readers) -->
+ * <ds-icon name="alert-triangle" label="Warning"></ds-icon>
+ * ```
+ */
+export class DsIcon extends DSElement {
+  static override styles = [];
+
+  /**
+   * The icon name from Lucide library (kebab-case).
+   * e.g., "search", "arrow-right", "external-link"
+   */
+  @property({ type: String, reflect: true })
+  name = "";
+
+  /**
+   * The icon size.
+   */
+  @property({ type: String, reflect: true })
+  size: IconSize = "md";
+
+  /**
+   * Accessible label for meaningful icons.
+   * When provided, the icon is announced to screen readers.
+   * When omitted, the icon is decorative and hidden from screen readers.
+   */
+  @property({ type: String })
+  label = "";
+
+  /**
+   * Custom color for the icon.
+   * Accepts any valid CSS color value.
+   * Default is currentColor (inherits from text color).
+   */
+  @property({ type: String })
+  color = "";
+
+  /**
+   * Cached SVG element
+   */
+  @state()
+  private _svgElement: SVGSVGElement | null = null;
+
+  /**
+   * Track if icon is valid
+   */
+  @state()
+  private _isValidIcon = true;
+
+  override willUpdate(changedProperties: Map<string, unknown>): void {
+    if (changedProperties.has("name") || changedProperties.has("size")) {
+      this.updateSvg();
+    }
+  }
+
+  private updateSvg(): void {
+    if (!this.name) {
+      this._svgElement = null;
+      this._isValidIcon = false;
+      return;
+    }
+
+    if (!hasIcon(this.name)) {
+      this._svgElement = null;
+      this._isValidIcon = false;
+      return;
+    }
+
+    this._svgElement = getIconSvg(this.name, {
+      size: SIZE_MAP[this.size],
+    });
+    this._isValidIcon = this._svgElement !== null;
+  }
+
+  override render(): TemplateResult {
+    const isDecorative = !this.label;
+
+    const classes = {
+      "ds-icon": true,
+      [`ds-icon--${this.size}`]: true,
+      "ds-icon--fallback": !this._isValidIcon,
+    };
+
+    const style = this.color ? `color: ${this.color}` : "";
+
+    // Render fallback if icon not found
+    if (!this._isValidIcon) {
+      return html`
+        <span
+          class=${classMap(classes)}
+          style=${style || nothing}
+          aria-hidden="true"
+        ></span>
+      `;
+    }
+
+    // Decorative icon (no label)
+    if (isDecorative) {
+      return html`
+        <span
+          class=${classMap(classes)}
+          style=${style || nothing}
+          aria-hidden="true"
+        >
+          ${this._svgElement}
+        </span>
+      `;
+    }
+
+    // Meaningful icon (with label)
+    return html`
+      <span
+        class=${classMap(classes)}
+        style=${style || nothing}
+        role="img"
+        aria-label=${this.label}
+      >
+        ${this._svgElement}
+      </span>
+    `;
+  }
+}
+
+// Register the component
+define("ds-icon", DsIcon);
+
+// TypeScript declaration for HTML
+declare global {
+  interface HTMLElementTagNameMap {
+    "ds-icon": DsIcon;
+  }
+}

package/templates/input/input.tsx

@@ -0,0 +1,130 @@
+import type React from "react";
+import { type InputHTMLAttributes, createElement, forwardRef, useEffect, useRef } from "react";
+import {
+  type ResponsiveProp,
+  generateResponsiveDataAttr,
+  isResponsiveObject,
+  resolveResponsiveValue,
+} from "@/lib/primitives/responsive";
+
+export type InputType = "text" | "email" | "password" | "number" | "tel" | "url" | "search";
+export type InputSize = "sm" | "md" | "lg";
+
+export interface InputProps
+  extends Omit<InputHTMLAttributes<HTMLInputElement>, "size" | "onChange" | "onInput"> {
+  /** Input type */
+  type?: InputType;
+  /**
+   * Input size - supports responsive object syntax
+   * @example
+   * ```tsx
+   * // Single value
+   * <Input size="md" />
+   *
+   * // Responsive
+   * <Input size={{ base: "sm", md: "md", lg: "lg" }} />
+   * ```
+   */
+  size?: ResponsiveProp<InputSize>;
+  /** Error state */
+  error?: boolean;
+  /** Change handler - fires when input loses focus with changed value */
+  onChange?: (value: string, event: Event) => void;
+  /** Value change handler - fires on every keystroke */
+  onValueChange?: (value: string, event: Event) => void;
+}
+
+/**
+ * React wrapper for ds-input Web Component.
+ * Provides type-safe props and event handling.
+ */
+export const Input = forwardRef<HTMLElement, InputProps>((props, forwardedRef) => {
+  const {
+    type = "text",
+    size = "md",
+    name,
+    value,
+    placeholder,
+    disabled = false,
+    readOnly = false,
+    required = false,
+    error = false,
+    minLength,
+    maxLength,
+    pattern,
+    onChange,
+    onValueChange,
+    className,
+    ...rest
+  } = props;
+
+  const internalRef = useRef<HTMLElement>(null);
+
+  // Merge refs
+  useEffect(() => {
+    if (typeof forwardedRef === "function") {
+      forwardedRef(internalRef.current);
+    } else if (forwardedRef) {
+      (forwardedRef as React.MutableRefObject<HTMLElement | null>).current = internalRef.current;
+    }
+  }, [forwardedRef]);
+
+  // Handle input events
+  useEffect(() => {
+    const element = internalRef.current;
+    if (!element) return;
+
+    const handleInputEvent = (event: Event) => {
+      const customEvent = event as CustomEvent<{ value: string }>;
+      onValueChange?.(customEvent.detail.value, event);
+    };
+
+    const handleChangeEvent = (event: Event) => {
+      const customEvent = event as CustomEvent<{ value: string }>;
+      onChange?.(customEvent.detail.value, event);
+    };
+
+    if (onValueChange) {
+      element.addEventListener("input", handleInputEvent);
+    }
+    if (onChange) {
+      element.addEventListener("change", handleChangeEvent);
+    }
+
+    return () => {
+      if (onValueChange) {
+        element.removeEventListener("input", handleInputEvent);
+      }
+      if (onChange) {
+        element.removeEventListener("change", handleChangeEvent);
+      }
+    };
+  }, [onValueChange, onChange]);
+
+  // 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-input", {
+    ref: internalRef,
+    type,
+    size: resolvedSize,
+    name,
+    value,
+    placeholder,
+    disabled: disabled || undefined,
+    readonly: readOnly || undefined,
+    required: required || undefined,
+    error: error || undefined,
+    minlength: minLength,
+    maxlength: maxLength,
+    pattern,
+    class: className,
+    // Add responsive data attribute for CSS targeting
+    "data-size-responsive": responsiveSizeAttr,
+    ...rest,
+  });
+});
+
+Input.displayName = "Input";

package/templates/input/wc/input.ts

@@ -0,0 +1,216 @@
+import { html } from "lit";
+import { property, state } from "lit/decorators.js";
+import { ifDefined } from "lit/directives/if-defined.js";
+import { DSElement } from "../../base/ds-element.js";
+import { StandardEvents, emitEvent } from "../../events/emit.js";
+import { define } from "../../registry/define.js";
+import { devWarn, hasAccessibleLabel, Warnings } from "../../utils/dev-warnings.js";
+
+export type InputType = "text" | "email" | "password" | "number" | "tel" | "url" | "search";
+export type InputSize = "sm" | "md" | "lg";
+
+/**
+ * A text input field component.
+ *
+ * @element ds-input
+ * @fires input - Fired when the input value changes
+ * @fires change - Fired when the input value is committed
+ *
+ * @example
+ * ```html
+ * <ds-field>
+ *   <ds-label>Email</ds-label>
+ *   <ds-input type="email" name="email"></ds-input>
+ * </ds-field>
+ * ```
+ */
+export class DsInput extends DSElement {
+  /** Input type */
+  @property({ type: String, reflect: true })
+  type: InputType = "text";
+
+  /** Input size */
+  @property({ type: String, reflect: true })
+  size: InputSize = "md";
+
+  /** Input name */
+  @property({ type: String, reflect: true })
+  name = "";
+
+  /** Input value */
+  @property({ type: String })
+  value = "";
+
+  /** Placeholder text */
+  @property({ type: String })
+  placeholder = "";
+
+  /** Disabled state */
+  @property({ type: Boolean, reflect: true })
+  disabled = false;
+
+  /** Read-only state */
+  @property({ type: Boolean, reflect: true })
+  readonly = false;
+
+  /** Required state */
+  @property({ type: Boolean, reflect: true })
+  required = false;
+
+  /** Error state */
+  @property({ type: Boolean, reflect: true })
+  error = false;
+
+  /** Minimum length */
+  @property({ type: Number })
+  minlength?: number;
+
+  /** Maximum length */
+  @property({ type: Number })
+  maxlength?: number;
+
+  /** Pattern for validation */
+  @property({ type: String })
+  pattern?: string;
+
+  /** ARIA labelledby - ID of element that labels this input */
+  @state()
+  private ariaLabelledBy?: string;
+
+  /** ARIA describedby - IDs of elements that describe this input */
+  @state()
+  private ariaDescribedBy?: string;
+
+  private attributeObserver: MutationObserver | null = null;
+
+  override connectedCallback(): void {
+    super.connectedCallback();
+
+    // Observe ARIA attribute changes on the host element
+    this.attributeObserver = new MutationObserver((mutations) => {
+      for (const mutation of mutations) {
+        if (mutation.type === "attributes") {
+          this.syncAriaAttributes();
+        }
+      }
+    });
+
+    this.attributeObserver.observe(this, {
+      attributes: true,
+      attributeFilter: [
+        "aria-labelledby",
+        "aria-describedby",
+        "aria-invalid",
+        "aria-required",
+        "aria-disabled",
+      ],
+    });
+
+    // Initial sync
+    this.syncAriaAttributes();
+
+    // Dev warning: Check for accessible label after DOM is ready
+    requestAnimationFrame(() => {
+      if (!hasAccessibleLabel(this)) {
+        // Also check if inside a ds-field with a label
+        const field = this.closest("ds-field");
+        const hasFieldLabel = field?.querySelector("ds-label") !== null;
+        if (!hasFieldLabel) {
+          devWarn(Warnings.inputMissingLabel("ds-input"));
+        }
+      }
+    });
+  }
+
+  override disconnectedCallback(): void {
+    super.disconnectedCallback();
+    this.attributeObserver?.disconnect();
+    this.attributeObserver = null;
+  }
+
+  /**
+   * Syncs ARIA attributes from the host element to internal state.
+   * The render method will apply these to the native input.
+   */
+  private syncAriaAttributes(): void {
+    this.ariaLabelledBy = this.getAttribute("aria-labelledby") ?? undefined;
+    this.ariaDescribedBy = this.getAttribute("aria-describedby") ?? undefined;
+
+    // Sync error state from aria-invalid
+    const ariaInvalid = this.getAttribute("aria-invalid");
+    if (ariaInvalid === "true") {
+      this.error = true;
+    } else if (ariaInvalid === "false") {
+      this.error = false;
+    }
+
+    // Sync required state from aria-required
+    const ariaRequired = this.getAttribute("aria-required");
+    if (ariaRequired === "true") {
+      this.required = true;
+    }
+
+    // Sync disabled state from aria-disabled
+    const ariaDisabled = this.getAttribute("aria-disabled");
+    if (ariaDisabled === "true") {
+      this.disabled = true;
+    }
+  }
+
+  private handleInput(event: Event) {
+    const input = event.target as HTMLInputElement;
+    this.value = input.value;
+    // Also emit native input event for compatibility
+    this.dispatchEvent(
+      new CustomEvent("input", {
+        detail: { value: this.value },
+        bubbles: true,
+        composed: true,
+      })
+    );
+  }
+
+  private handleChange(event: Event) {
+    const input = event.target as HTMLInputElement;
+    this.value = input.value;
+    // Emit ds:change event using standard convention
+    emitEvent(this, StandardEvents.CHANGE, {
+      detail: { value: this.value },
+    });
+  }
+
+  override render() {
+    return html`
+      <div class="ds-input" part="container" data-size=${this.size}>
+        <input
+          part="input"
+          class="ds-input__field"
+          type=${this.type}
+          name=${this.name}
+          .value=${this.value}
+          placeholder=${this.placeholder}
+          ?disabled=${this.disabled}
+          ?readonly=${this.readonly}
+          ?required=${this.required}
+          aria-invalid=${this.error ? "true" : "false"}
+          aria-labelledby=${ifDefined(this.ariaLabelledBy)}
+          aria-describedby=${ifDefined(this.ariaDescribedBy)}
+          aria-required=${this.required ? "true" : "false"}
+          minlength=${this.minlength ?? ""}
+          maxlength=${this.maxlength ?? ""}
+          pattern=${this.pattern ?? ""}
+          @input=${this.handleInput}
+          @change=${this.handleChange}
+        />
+      </div>
+    `;
+  }
+}
+
+define("ds-input", DsInput);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "ds-input": DsInput;
+  }
+}