@hypoth-ui/cli 0.0.1 → 0.1.0

package/templates/field/index.ts

@@ -0,0 +1,4 @@
+export { Field, type FieldProps } from "./field.js";
+export { Label, type LabelProps } from "./label.js";
+export { FieldDescription, type FieldDescriptionProps } from "./field-description.js";
+export { FieldError, type FieldErrorProps } from "./field-error.js";

package/templates/field/label.tsx

@@ -0,0 +1,40 @@
+import type React from "react";
+import { type HTMLAttributes, createElement, forwardRef, useEffect, useRef } from "react";
+
+export interface LabelProps extends HTMLAttributes<HTMLElement> {
+  /** For attribute linking to input */
+  htmlFor?: string;
+  /** Label content */
+  children?: React.ReactNode;
+}
+
+/**
+ * React wrapper for ds-label Web Component.
+ * Label for form fields with automatic ID association.
+ */
+export const Label = forwardRef<HTMLElement, LabelProps>((props, forwardedRef) => {
+  const { htmlFor, children, className, ...rest } = props;
+
+  const internalRef = useRef<HTMLElement>(null);
+
+  useEffect(() => {
+    if (typeof forwardedRef === "function") {
+      forwardedRef(internalRef.current);
+    } else if (forwardedRef) {
+      (forwardedRef as React.MutableRefObject<HTMLElement | null>).current = internalRef.current;
+    }
+  }, [forwardedRef]);
+
+  return createElement(
+    "ds-label",
+    {
+      ref: internalRef,
+      for: htmlFor,
+      class: className,
+      ...rest,
+    },
+    children
+  );
+});
+
+Label.displayName = "Label";

package/templates/field/wc/field-description.ts

@@ -0,0 +1,42 @@
+import { html } from "lit";
+import { DSElement } from "../../base/ds-element.js";
+import { define } from "../../registry/define.js";
+
+/**
+ * Description/help text component for form fields.
+ *
+ * Used within ds-field to provide supplementary help text that is
+ * automatically associated with the form control via aria-describedby.
+ *
+ * @element ds-field-description
+ *
+ * @slot - Description text content
+ *
+ * @example
+ * ```html
+ * <ds-field>
+ *   <ds-label>Password</ds-label>
+ *   <ds-input type="password"></ds-input>
+ *   <ds-field-description>
+ *     Must be at least 8 characters with one number
+ *   </ds-field-description>
+ * </ds-field>
+ * ```
+ */
+export class DsFieldDescription extends DSElement {
+  override render() {
+    return html`
+      <div class="ds-field-description" part="description">
+        <slot></slot>
+      </div>
+    `;
+  }
+}
+
+define("ds-field-description", DsFieldDescription);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "ds-field-description": DsFieldDescription;
+  }
+}

package/templates/field/wc/field-error.ts

@@ -0,0 +1,46 @@
+import { html } from "lit";
+import { DSElement } from "../../base/ds-element.js";
+import { define } from "../../registry/define.js";
+
+/**
+ * Error message component for form fields.
+ *
+ * Used within ds-field to display validation error messages that are
+ * automatically associated with the form control via aria-describedby.
+ * Error messages take precedence over descriptions in the ARIA description.
+ *
+ * @element ds-field-error
+ *
+ * @slot - Error message text content
+ *
+ * @example
+ * ```html
+ * <ds-field>
+ *   <ds-label>Email</ds-label>
+ *   <ds-input type="email" error></ds-input>
+ *   <ds-field-error>Please enter a valid email address</ds-field-error>
+ * </ds-field>
+ * ```
+ */
+export class DsFieldError extends DSElement {
+  override render() {
+    return html`
+      <div
+        class="ds-field-error"
+        part="error"
+        role="alert"
+        aria-live="polite"
+      >
+        <slot></slot>
+      </div>
+    `;
+  }
+}
+
+define("ds-field-error", DsFieldError);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "ds-field-error": DsFieldError;
+  }
+}

package/templates/field/wc/field.ts

@@ -0,0 +1,210 @@
+import { html } from "lit";
+import { property, state } from "lit/decorators.js";
+import { DSElement } from "../../base/ds-element.js";
+import { define } from "../../registry/define.js";
+
+// Import child components to ensure they're registered
+import "./label.js";
+import "./field-description.js";
+import "./field-error.js";
+
+/**
+ * Field container component for form controls.
+ *
+ * Provides consistent layout and automatic ARIA attribute composition
+ * for form fields. Associates labels, descriptions, and error messages
+ * with the form control for accessibility.
+ *
+ * @element ds-field
+ *
+ * @slot - Field contents (label, form control, description, error)
+ *
+ * @csspart container - The field container element
+ *
+ * @cssprop --ds-field-gap - Gap between field children (default: 0.5rem)
+ * @cssprop --ds-field-error-color - Error message color
+ *
+ * @example
+ * ```html
+ * <ds-field required>
+ *   <ds-label>Email address</ds-label>
+ *   <ds-field-description>We'll never share your email</ds-field-description>
+ *   <ds-input type="email" name="email"></ds-input>
+ *   <ds-field-error>Please enter a valid email</ds-field-error>
+ * </ds-field>
+ * ```
+ */
+export class DsField extends DSElement {
+  /** Marks the field as required */
+  @property({ type: Boolean, reflect: true })
+  required = false;
+
+  /** Whether the field is disabled */
+  @property({ type: Boolean, reflect: true })
+  disabled = false;
+
+  /** Generated unique ID for ARIA associations */
+  @state()
+  private fieldId = "";
+
+  /** Whether an error child is present */
+  @state()
+  private hasError = false;
+
+  /** Whether a description child is present */
+  @state()
+  private hasDescription = false;
+
+  private observer: MutationObserver | null = null;
+
+  override connectedCallback(): void {
+    super.connectedCallback();
+
+    // Generate unique ID for this field instance
+    this.fieldId = `field-${crypto.randomUUID().slice(0, 8)}`;
+
+    // Set up mutation observer to track child changes
+    this.observer = new MutationObserver(() => this.updateChildComponents());
+    this.observer.observe(this, { childList: true, subtree: true });
+
+    // Initial setup after first render
+    this.updateComplete.then(() => {
+      this.updateChildComponents();
+    });
+  }
+
+  override disconnectedCallback(): void {
+    super.disconnectedCallback();
+    this.observer?.disconnect();
+    this.observer = null;
+  }
+
+  /**
+   * Updates ARIA attributes on child components based on field structure.
+   */
+  private updateChildComponents(): void {
+    // Find child components
+    const label = this.querySelector("ds-label");
+    const description = this.querySelector("ds-field-description");
+    const error = this.querySelector("ds-field-error");
+    const formControl = this.querySelector(
+      "ds-input, ds-textarea, ds-checkbox, ds-radio-group, ds-switch, ds-select, ds-combobox, ds-date-picker, ds-slider, ds-number-input, ds-file-upload, ds-time-picker, ds-pin-input, input, textarea, select"
+    );
+
+    // Track which components are present
+    this.hasError = !!error && error.textContent?.trim() !== "";
+    this.hasDescription = !!description && description.textContent?.trim() !== "";
+
+    // Assign IDs to components
+    if (label) {
+      const labelId = `${this.fieldId}-label`;
+      label.id = labelId;
+
+      // Set data-required on label for styling
+      if (this.required) {
+        label.setAttribute("data-required", "");
+      } else {
+        label.removeAttribute("data-required");
+      }
+    }
+
+    if (description) {
+      description.id = `${this.fieldId}-desc`;
+    }
+
+    if (error) {
+      error.id = `${this.fieldId}-error`;
+    }
+
+    // Compose ARIA attributes for form control
+    if (formControl) {
+      // Build aria-labelledby
+      if (label) {
+        formControl.setAttribute("aria-labelledby", label.id);
+      }
+
+      // Build aria-describedby (error first, then description)
+      const describedByIds: string[] = [];
+      if (this.hasError && error) {
+        describedByIds.push(error.id);
+      }
+      if (this.hasDescription && description) {
+        describedByIds.push(description.id);
+      }
+
+      if (describedByIds.length > 0) {
+        formControl.setAttribute("aria-describedby", describedByIds.join(" "));
+      } else {
+        formControl.removeAttribute("aria-describedby");
+      }
+
+      // Set aria-invalid if error is present
+      if (this.hasError) {
+        formControl.setAttribute("aria-invalid", "true");
+        // Also set error property if it's a design system component
+        if ("error" in formControl) {
+          (formControl as { error: boolean }).error = true;
+        }
+      } else {
+        formControl.setAttribute("aria-invalid", "false");
+        if ("error" in formControl) {
+          (formControl as { error: boolean }).error = false;
+        }
+      }
+
+      // Set aria-required if field is required
+      if (this.required) {
+        formControl.setAttribute("aria-required", "true");
+        if ("required" in formControl) {
+          (formControl as { required: boolean }).required = true;
+        }
+      }
+
+      // Set disabled state
+      if (this.disabled) {
+        formControl.setAttribute("aria-disabled", "true");
+        if ("disabled" in formControl) {
+          (formControl as { disabled: boolean }).disabled = true;
+        }
+      }
+    }
+
+    // Update data attributes on self for CSS styling
+    if (this.hasError) {
+      this.setAttribute("data-error", "");
+    } else {
+      this.removeAttribute("data-error");
+    }
+
+    if (this.disabled) {
+      this.setAttribute("data-disabled", "");
+    } else {
+      this.removeAttribute("data-disabled");
+    }
+  }
+
+  override updated(changedProperties: Map<string, unknown>): void {
+    super.updated(changedProperties);
+
+    // Re-apply ARIA attributes when required or disabled changes
+    if (changedProperties.has("required") || changedProperties.has("disabled")) {
+      this.updateChildComponents();
+    }
+  }
+
+  override render() {
+    return html`
+      <div class="ds-field" part="container">
+        <slot @slotchange=${this.updateChildComponents}></slot>
+      </div>
+    `;
+  }
+}
+
+define("ds-field", DsField);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "ds-field": DsField;
+  }
+}

package/templates/field/wc/label.ts

@@ -0,0 +1,54 @@
+import { html } from "lit";
+import { property } from "lit/decorators.js";
+import { DSElement } from "../../base/ds-element.js";
+import { define } from "../../registry/define.js";
+
+/**
+ * Label component for form fields.
+ *
+ * Used within ds-field to provide an accessible label that is
+ * automatically associated with the form control via aria-labelledby.
+ *
+ * @element ds-label
+ *
+ * @slot - Label text content
+ *
+ * @example
+ * ```html
+ * <ds-field>
+ *   <ds-label>Email address</ds-label>
+ *   <ds-input type="email"></ds-input>
+ * </ds-field>
+ * ```
+ */
+export class DsLabel extends DSElement {
+  /**
+   * ID of the associated form control.
+   * Typically set automatically by the parent ds-field component.
+   */
+  @property({ type: String, attribute: "for" })
+  for = "";
+
+  override render() {
+    return html`
+      <label
+        class="ds-label"
+        part="label"
+        for=${this.for || nothing}
+      >
+        <slot></slot>
+      </label>
+    `;
+  }
+}
+
+// Import nothing for conditional attributes
+import { nothing } from "lit";
+
+define("ds-label", DsLabel);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "ds-label": DsLabel;
+  }
+}

package/templates/file-upload/file-upload-context.ts

@@ -0,0 +1,26 @@
+/**
+ * FileUpload context for compound component pattern.
+ */
+
+import type { FileInfo, FileUploadBehavior } from "@hypoth-ui/primitives-dom";
+import { createCompoundContext } from "../../utils/create-context.js";
+
+export interface FileUploadContextValue {
+  /** FileUpload behavior instance */
+  behavior: FileUploadBehavior;
+  /** Current files */
+  files: FileInfo[];
+  /** Is dragging over dropzone */
+  isDragging: boolean;
+  /** Set dragging state */
+  setIsDragging: (dragging: boolean) => void;
+  /** Input ref for triggering file dialog */
+  inputRef: React.RefObject<HTMLInputElement>;
+  /** Open file dialog */
+  openFileDialog: () => void;
+  /** Disabled state */
+  disabled: boolean;
+}
+
+export const [FileUploadProvider, useFileUploadContext] =
+  createCompoundContext<FileUploadContextValue>("FileUpload");

package/templates/file-upload/file-upload-dropzone.tsx

@@ -0,0 +1,111 @@
+/**
+ * FileUpload Dropzone component - the drop target area.
+ */
+
+import {
+  type DragEvent,
+  type HTMLAttributes,
+  type KeyboardEvent,
+  type ReactNode,
+  forwardRef,
+  useCallback,
+} from "react";
+import { useFileUploadContext } from "./file-upload-context.js";
+
+export interface FileUploadDropzoneProps extends HTMLAttributes<HTMLDivElement> {
+  /** Dropzone content */
+  children?: ReactNode;
+}
+
+/**
+ * The dropzone area for drag-and-drop file uploads.
+ * Also handles click-to-upload functionality.
+ *
+ * @example
+ * ```tsx
+ * <FileUpload.Dropzone className="dropzone">
+ *   <p>Drop files here or click to upload</p>
+ * </FileUpload.Dropzone>
+ * ```
+ */
+export const FileUploadDropzone = forwardRef<HTMLDivElement, FileUploadDropzoneProps>(
+  ({ children, className, onClick, onKeyDown, ...restProps }, ref) => {
+    const { behavior, isDragging, setIsDragging, openFileDialog, disabled } =
+      useFileUploadContext("FileUpload.Dropzone");
+
+    const dropzoneProps = behavior.getDropzoneProps();
+
+    const handleClick = useCallback(
+      (event: React.MouseEvent<HTMLDivElement>) => {
+        openFileDialog();
+        onClick?.(event);
+      },
+      [openFileDialog, onClick]
+    );
+
+    const handleKeyDown = useCallback(
+      (event: KeyboardEvent<HTMLDivElement>) => {
+        if (behavior.handleKeyDown(event.nativeEvent)) {
+          openFileDialog();
+        }
+        onKeyDown?.(event);
+      },
+      [behavior, openFileDialog, onKeyDown]
+    );
+
+    const handleDragEnter = useCallback(
+      (event: DragEvent<HTMLDivElement>) => {
+        behavior.handleDragEnter(event.nativeEvent);
+        setIsDragging(behavior.state.isDragging);
+      },
+      [behavior, setIsDragging]
+    );
+
+    const handleDragLeave = useCallback(
+      (event: DragEvent<HTMLDivElement>) => {
+        behavior.handleDragLeave(event.nativeEvent);
+        setIsDragging(behavior.state.isDragging);
+      },
+      [behavior, setIsDragging]
+    );
+
+    const handleDragOver = useCallback(
+      (event: DragEvent<HTMLDivElement>) => {
+        behavior.handleDragOver(event.nativeEvent);
+      },
+      [behavior]
+    );
+
+    const handleDrop = useCallback(
+      (event: DragEvent<HTMLDivElement>) => {
+        behavior.handleDrop(event.nativeEvent);
+        setIsDragging(false);
+      },
+      [behavior, setIsDragging]
+    );
+
+    return (
+      <div
+        ref={ref}
+        role={dropzoneProps.role}
+        tabIndex={dropzoneProps.tabIndex}
+        aria-label={dropzoneProps["aria-label"]}
+        aria-disabled={dropzoneProps["aria-disabled"]}
+        className={className}
+        data-dragging={isDragging || undefined}
+        data-disabled={disabled || undefined}
+        onClick={handleClick}
+        onKeyDown={handleKeyDown}
+        onDragEnter={handleDragEnter}
+        onDragLeave={handleDragLeave}
+        onDragOver={handleDragOver}
+        onDrop={handleDrop}
+        {...restProps}
+      >
+        {children}
+      </div>
+    );
+  }
+);
+
+FileUploadDropzone.displayName = "FileUpload.Dropzone";

package/templates/file-upload/file-upload-input.tsx

@@ -0,0 +1,86 @@
+/**
+ * FileUpload Input component - hidden file input element.
+ */
+
+import { type ChangeEvent, type InputHTMLAttributes, forwardRef, useCallback } from "react";
+import { useFileUploadContext } from "./file-upload-context.js";
+
+export interface FileUploadInputProps
+  extends Omit<InputHTMLAttributes<HTMLInputElement>, "type" | "onChange"> {}
+
+/**
+ * Hidden file input element that handles file selection.
+ * Must be rendered within FileUpload.Root.
+ *
+ * @example
+ * ```tsx
+ * <FileUpload.Root>
+ *   <FileUpload.Input />
+ *   <FileUpload.Dropzone>...</FileUpload.Dropzone>
+ * </FileUpload.Root>
+ * ```
+ */
+export const FileUploadInput = forwardRef<HTMLInputElement, FileUploadInputProps>(
+  ({ className, style, ...restProps }, ref) => {
+    const { behavior, inputRef, disabled } = useFileUploadContext("FileUpload.Input");
+
+    const inputProps = behavior.getInputProps();
+
+    const handleChange = useCallback(
+      (event: ChangeEvent<HTMLInputElement>) => {
+        const input = event.target;
+        if (input.files && input.files.length > 0) {
+          behavior.addFiles(input.files);
+          // Reset input so the same file can be selected again
+          input.value = "";
+        }
+      },
+      [behavior]
+    );
+
+    // Merge refs
+    const mergedRef = useCallback(
+      (element: HTMLInputElement | null) => {
+        (inputRef as React.MutableRefObject<HTMLInputElement | null>).current = element;
+        if (typeof ref === "function") {
+          ref(element);
+        } else if (ref) {
+          (ref as React.MutableRefObject<HTMLInputElement | null>).current = element;
+        }
+      },
+      [inputRef, ref]
+    );
+
+    // Default hidden styles
+    const hiddenStyles: React.CSSProperties = {
+      position: "absolute",
+      width: 1,
+      height: 1,
+      padding: 0,
+      margin: -1,
+      overflow: "hidden",
+      clip: "rect(0, 0, 0, 0)",
+      whiteSpace: "nowrap",
+      border: 0,
+      ...style,
+    };
+
+    return (
+      <input
+        ref={mergedRef}
+        type={inputProps.type}
+        accept={inputProps.accept}
+        multiple={inputProps.multiple}
+        disabled={disabled || inputProps.disabled}
+        aria-hidden={inputProps["aria-hidden"]}
+        tabIndex={inputProps.tabIndex}
+        className={className}
+        style={hiddenStyles}
+        onChange={handleChange}
+        {...restProps}
+      />
+    );
+  }
+);
+
+FileUploadInput.displayName = "FileUpload.Input";