@hypoth-ui/cli 0.0.1 → 0.1.0

package/templates/switch/switch.tsx

@@ -0,0 +1,90 @@
+import type React from "react";
+import {
+  type HTMLAttributes,
+  createElement,
+  forwardRef,
+  useCallback,
+  useEffect,
+  useRef,
+} from "react";
+
+export interface SwitchProps extends Omit<HTMLAttributes<HTMLElement>, "onChange"> {
+  /** Switch name */
+  name?: string;
+  /** Whether checked/on */
+  checked?: boolean;
+  /** Default checked state (uncontrolled) */
+  defaultChecked?: boolean;
+  /** Whether disabled */
+  disabled?: boolean;
+  /** Whether required */
+  required?: boolean;
+  /** Change handler */
+  onChange?: (checked: boolean, event: Event) => void;
+  /** Switch label content */
+  children?: React.ReactNode;
+}
+
+/**
+ * React wrapper for ds-switch Web Component.
+ * Toggle switch with role="switch".
+ */
+export const Switch = forwardRef<HTMLElement, SwitchProps>((props, forwardedRef) => {
+  const {
+    name,
+    checked,
+    defaultChecked,
+    disabled = false,
+    required = false,
+    onChange,
+    children,
+    className,
+    ...rest
+  } = props;
+
+  const internalRef = useRef<HTMLElement>(null);
+
+  // Store handler in ref for stable callback reference
+  const onChangeRef = useRef(onChange);
+  onChangeRef.current = onChange;
+
+  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 handleChange = useCallback((event: Event) => {
+    const customEvent = event as CustomEvent<{ checked: boolean }>;
+    onChangeRef.current?.(customEvent.detail.checked, event);
+  }, []);
+
+  // Handle change events - no handler deps needed
+  useEffect(() => {
+    const element = internalRef.current;
+    if (!element) return;
+
+    element.addEventListener("ds:change", handleChange);
+    return () => element.removeEventListener("ds:change", handleChange);
+  }, [handleChange]);
+
+  return createElement(
+    "ds-switch",
+    {
+      ref: internalRef,
+      name,
+      checked: checked || undefined,
+      "default-checked": defaultChecked || undefined,
+      disabled: disabled || undefined,
+      required: required || undefined,
+      class: className,
+      ...rest,
+    },
+    children
+  );
+});
+
+Switch.displayName = "Switch";

package/templates/switch/wc/switch.ts

@@ -0,0 +1,228 @@
+import { html } from "lit";
+import type { PropertyValues } 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 { FormAssociatedMixin } from "../../base/form-associated.js";
+import type { ValidationFlags } from "../../base/form-associated.js";
+import { StandardEvents, emitEvent } from "../../events/emit.js";
+import { define } from "../../registry/define.js";
+
+/**
+ * Toggle switch for boolean settings with role="switch" semantics and native form participation.
+ *
+ * Uses ElementInternals for form association - values are submitted with the form
+ * and the switch participates in constraint validation.
+ *
+ * @element ds-switch
+ * @fires ds:change - Fired on state change with { checked }
+ * @fires ds:invalid - Fired when customValidation is true and validation fails
+ *
+ * @slot - Switch label
+ *
+ * @example
+ * ```html
+ * <form>
+ *   <ds-switch name="notifications">Enable notifications</ds-switch>
+ *   <button type="submit">Submit</button>
+ * </form>
+ *
+ * <ds-field>
+ *   <ds-label>Dark Mode</ds-label>
+ *   <ds-switch name="darkMode" custom-validation>Enable dark mode</ds-switch>
+ *   <ds-field-description>Switch between light and dark themes</ds-field-description>
+ *   <ds-field-error></ds-field-error>
+ * </ds-field>
+ * ```
+ */
+export class DsSwitch extends FormAssociatedMixin(DSElement) {
+  /** Checked (on) state */
+  @property({ type: Boolean, reflect: true })
+  checked = false;
+
+  /** ARIA describedby - IDs of elements that describe this switch */
+  @state()
+  private ariaDescribedBy?: string;
+
+  /** Label text captured from slot */
+  @state()
+  private labelText = "";
+
+  /** Unique ID for label association */
+  @state()
+  private labelId = "";
+
+  /** Default checked state for form reset */
+  private _defaultChecked = false;
+
+  private attributeObserver: MutationObserver | null = null;
+
+  override connectedCallback(): void {
+    // Capture label text before Lit renders
+    this.labelText = this.textContent?.trim() ?? "";
+    // Generate unique ID for label
+    this.labelId = `switch-label-${crypto.randomUUID().slice(0, 8)}`;
+    // Store default checked state
+    this._defaultChecked = this.checked;
+
+    super.connectedCallback();
+
+    // Set default value for form association
+    if (!this.value) {
+      this.value = "on";
+    }
+
+    // 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-describedby", "aria-invalid", "aria-required", "aria-disabled"],
+    });
+
+    // Initial sync
+    this.syncAriaAttributes();
+  }
+
+  override disconnectedCallback(): void {
+    super.disconnectedCallback();
+    this.attributeObserver?.disconnect();
+    this.attributeObserver = null;
+  }
+
+  /**
+   * Syncs ARIA attributes from the host element to internal state.
+   */
+  private syncAriaAttributes(): void {
+    this.ariaDescribedBy = this.getAttribute("aria-describedby") ?? undefined;
+
+    // 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;
+    }
+  }
+
+  /**
+   * Toggles the switch state.
+   */
+  private toggle(): void {
+    if (this.disabled) return;
+
+    this.checked = !this.checked;
+
+    emitEvent(this, StandardEvents.CHANGE, {
+      detail: {
+        checked: this.checked,
+      },
+    });
+  }
+
+  private handleClick = (event: Event): void => {
+    event.preventDefault();
+    this.toggle();
+  };
+
+  private handleKeyDown = (event: KeyboardEvent): void => {
+    // Both Space and Enter keys toggle the switch (distinct from checkbox)
+    if ((event.key === " " || event.key === "Enter") && !this.disabled) {
+      event.preventDefault();
+      this.toggle();
+    }
+  };
+
+  // Form association implementation
+
+  protected getFormValue(): string | null {
+    return this.checked ? this.value : null;
+  }
+
+  protected getValidationAnchor(): HTMLElement | undefined {
+    return this.querySelector(".ds-switch__control") as HTMLElement | undefined;
+  }
+
+  protected getValidationFlags(): ValidationFlags {
+    if (this.required && !this.checked) {
+      return { valueMissing: true };
+    }
+    return {};
+  }
+
+  protected getValidationMessage(flags: ValidationFlags): string {
+    if (flags.valueMissing) {
+      return "Please turn this switch on to proceed";
+    }
+    return "";
+  }
+
+  protected shouldUpdateFormValue(changedProperties: PropertyValues): boolean {
+    return changedProperties.has("checked");
+  }
+
+  protected shouldUpdateValidity(changedProperties: PropertyValues): boolean {
+    return changedProperties.has("checked");
+  }
+
+  protected onFormReset(): void {
+    this.checked = this._defaultChecked;
+  }
+
+  protected onFormStateRestore(
+    state: string | File | FormData | null,
+    _mode: "restore" | "autocomplete"
+  ): void {
+    if (typeof state === "string") {
+      this.checked = state === this.value;
+    }
+  }
+
+  override render() {
+    return html`
+      <div
+        class="ds-switch"
+        part="container"
+        @click=${this.handleClick}
+      >
+        <div
+          role="switch"
+          part="control"
+          class="ds-switch__control"
+          tabindex=${this.disabled ? -1 : 0}
+          aria-checked=${this.checked ? "true" : "false"}
+          aria-disabled=${this.disabled ? "true" : "false"}
+          aria-required=${this.required ? "true" : "false"}
+          aria-labelledby=${this.labelId}
+          aria-describedby=${ifDefined(this.ariaDescribedBy)}
+          @keydown=${this.handleKeyDown}
+        >
+          <span class="ds-switch__track" part="track">
+            <span class="ds-switch__thumb" part="thumb"></span>
+          </span>
+        </div>
+        <span id=${this.labelId} class="ds-switch__label" part="label">
+          ${this.labelText}
+        </span>
+      </div>
+    `;
+  }
+}
+
+define("ds-switch", DsSwitch);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "ds-switch": DsSwitch;
+  }
+}

package/templates/table/body.tsx

@@ -0,0 +1,21 @@
+"use client";
+
+import { type HTMLAttributes, type ReactNode, createElement, forwardRef } from "react";
+import "@hypoth-ui/wc";
+
+export interface TableBodyProps extends HTMLAttributes<HTMLElement> {
+  /**
+   * Table body rows.
+   */
+  children?: ReactNode;
+}
+
+/**
+ * Table body component (tbody).
+ */
+export const TableBody = forwardRef<HTMLElement, TableBodyProps>(function TableBody(
+  { children, className, ...props },
+  ref
+) {
+  return createElement("ds-table-body", { ref, class: className, ...props }, children);
+});

package/templates/table/cell.tsx

@@ -0,0 +1,44 @@
+"use client";
+
+import { type HTMLAttributes, type ReactNode, createElement, forwardRef } from "react";
+import "@hypoth-ui/wc";
+import type { TableAlign } from "./head.js";
+
+export interface TableCellProps extends HTMLAttributes<HTMLElement> {
+  /**
+   * Text alignment.
+   * @default "left"
+   */
+  align?: TableAlign;
+
+  /**
+   * Column span.
+   * @default 1
+   */
+  colSpan?: number;
+
+  /**
+   * Row span.
+   * @default 1
+   */
+  rowSpan?: number;
+
+  /**
+   * Cell content.
+   */
+  children?: ReactNode;
+}
+
+/**
+ * Table cell component (td).
+ */
+export const TableCell = forwardRef<HTMLElement, TableCellProps>(function TableCell(
+  { align = "left", colSpan = 1, rowSpan = 1, children, className, ...props },
+  ref
+) {
+  return createElement(
+    "ds-table-cell",
+    { ref, align, colspan: colSpan, rowspan: rowSpan, class: className, ...props },
+    children
+  );
+});

package/templates/table/head.tsx

@@ -0,0 +1,112 @@
+"use client";
+
+import {
+  type HTMLAttributes,
+  type ReactNode,
+  createElement,
+  forwardRef,
+  useEffect,
+  useRef,
+} from "react";
+import "@hypoth-ui/wc";
+
+export type TableAlign = "left" | "center" | "right";
+export type SortDirection = "asc" | "desc" | "none";
+
+export interface TableHeadProps extends HTMLAttributes<HTMLElement> {
+  /**
+   * Column key for sorting.
+   */
+  column?: string;
+
+  /**
+   * Text alignment.
+   * @default "left"
+   */
+  align?: TableAlign;
+
+  /**
+   * Whether this column is sortable.
+   * @default false
+   */
+  sortable?: boolean;
+
+  /**
+   * Current sort direction.
+   * @default "none"
+   */
+  sortDirection?: SortDirection;
+
+  /**
+   * Column width (CSS value).
+   */
+  width?: string;
+
+  /**
+   * Callback when sort is triggered.
+   */
+  onSort?: (column: string, direction: SortDirection) => void;
+
+  /**
+   * Header cell content.
+   */
+  children?: ReactNode;
+}
+
+/**
+ * Table header cell component (th).
+ */
+export const TableHead = forwardRef<HTMLElement, TableHeadProps>(function TableHead(
+  {
+    column,
+    align = "left",
+    sortable = false,
+    sortDirection = "none",
+    width,
+    onSort,
+    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 handleSort = (e: Event) => {
+      const event = e as CustomEvent<{ column: string; direction: SortDirection }>;
+      onSort?.(event.detail.column, event.detail.direction);
+    };
+
+    element.addEventListener("ds:sort", handleSort);
+    return () => element.removeEventListener("ds:sort", handleSort);
+  }, [onSort]);
+
+  return createElement(
+    "ds-table-head",
+    {
+      ref: internalRef,
+      column,
+      align,
+      sortable: sortable || undefined,
+      "sort-direction": sortDirection,
+      width,
+      class: className,
+      ...props,
+    },
+    children
+  );
+});

package/templates/table/header.tsx

@@ -0,0 +1,21 @@
+"use client";
+
+import { type HTMLAttributes, type ReactNode, createElement, forwardRef } from "react";
+import "@hypoth-ui/wc";
+
+export interface TableHeaderProps extends HTMLAttributes<HTMLElement> {
+  /**
+   * Table header rows.
+   */
+  children?: ReactNode;
+}
+
+/**
+ * Table header component (thead).
+ */
+export const TableHeader = forwardRef<HTMLElement, TableHeaderProps>(function TableHeader(
+  { children, className, ...props },
+  ref
+) {
+  return createElement("ds-table-header", { ref, class: className, ...props }, children);
+});

package/templates/table/index.tsx

@@ -0,0 +1,93 @@
+"use client";
+
+/**
+ * Table compound component exports
+ */
+
+import { TableBody } from "./body.js";
+import { TableCell } from "./cell.js";
+import { TableHead } from "./head.js";
+import { TableHeader } from "./header.js";
+import { TableRoot } from "./root.js";
+import { TableRow } from "./row.js";
+
+export type { TableRootProps, TableSize } from "./root.js";
+export type { TableHeaderProps } from "./header.js";
+export type { TableBodyProps } from "./body.js";
+export type { TableRowProps } from "./row.js";
+export type { TableHeadProps, TableAlign, SortDirection } from "./head.js";
+export type { TableCellProps } from "./cell.js";
+
+/**
+ * Table compound component for structured data display.
+ *
+ * @example
+ * ```tsx
+ * <Table striped>
+ *   <Table.Header>
+ *     <Table.Row>
+ *       <Table.Head sortable column="name" onSort={handleSort}>Name</Table.Head>
+ *       <Table.Head>Email</Table.Head>
+ *     </Table.Row>
+ *   </Table.Header>
+ *   <Table.Body>
+ *     <Table.Row>
+ *       <Table.Cell>John Doe</Table.Cell>
+ *       <Table.Cell>john@example.com</Table.Cell>
+ *     </Table.Row>
+ *   </Table.Body>
+ * </Table>
+ * ```
+ */
+export const Table = Object.assign(TableRoot, {
+  Header: TableHeader,
+  Body: TableBody,
+  Row: TableRow,
+  Head: TableHead,
+  Cell: TableCell,
+});
+
+export { TableHeader, TableBody, TableRow, TableHead, TableCell };
+
+// TypeScript declarations for JSX
+declare global {
+  namespace JSX {
+    interface IntrinsicElements {
+      "ds-table": React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
+        ref?: React.Ref<HTMLElement>;
+        size?: string;
+        striped?: boolean;
+        borderless?: boolean;
+        fixed?: boolean;
+        "sticky-header"?: boolean;
+        caption?: string;
+      };
+      "ds-table-header": React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
+        ref?: React.Ref<HTMLElement>;
+      };
+      "ds-table-body": React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
+        ref?: React.Ref<HTMLElement>;
+      };
+      "ds-table-row": React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
+        ref?: React.Ref<HTMLElement>;
+        "row-id"?: string;
+        selected?: boolean;
+      };
+      "ds-table-head": React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
+        ref?: React.Ref<HTMLElement>;
+        column?: string;
+        align?: string;
+        sortable?: boolean;
+        "sort-direction"?: string;
+        width?: string;
+        "onDs-sort"?: (event: CustomEvent) => void;
+      };
+      "ds-table-cell": React.DetailedHTMLProps<React.HTMLAttributes<HTMLElement>, HTMLElement> & {
+        ref?: React.Ref<HTMLElement>;
+        align?: string;
+        colspan?: number;
+        rowspan?: number;
+      };
+    }
+  }
+}

package/templates/table/root.tsx

@@ -0,0 +1,82 @@
+"use client";
+
+import { type HTMLAttributes, type ReactNode, createElement, forwardRef } from "react";
+import "@hypoth-ui/wc";
+
+export type TableSize = "compact" | "default" | "spacious";
+
+export interface TableRootProps extends HTMLAttributes<HTMLElement> {
+  /**
+   * Size variant.
+   * @default "default"
+   */
+  size?: TableSize;
+
+  /**
+   * Whether to show striped rows.
+   * @default false
+   */
+  striped?: boolean;
+
+  /**
+   * Whether to remove borders.
+   * @default false
+   */
+  borderless?: boolean;
+
+  /**
+   * Whether to use fixed layout.
+   * @default false
+   */
+  fixed?: boolean;
+
+  /**
+   * Whether header is sticky.
+   * @default false
+   */
+  stickyHeader?: boolean;
+
+  /**
+   * Accessible caption for screen readers.
+   */
+  caption?: string;
+
+  /**
+   * Table content.
+   */
+  children?: ReactNode;
+}
+
+/**
+ * Table root component.
+ */
+export const TableRoot = forwardRef<HTMLElement, TableRootProps>(function TableRoot(
+  {
+    size = "default",
+    striped = false,
+    borderless = false,
+    fixed = false,
+    stickyHeader = false,
+    caption,
+    children,
+    className,
+    ...props
+  },
+  ref
+) {
+  return createElement(
+    "ds-table",
+    {
+      ref,
+      size,
+      striped: striped || undefined,
+      borderless: borderless || undefined,
+      fixed: fixed || undefined,
+      "sticky-header": stickyHeader || undefined,
+      caption,
+      class: className,
+      ...props,
+    },
+    children
+  );
+});