@hypoth-ui/cli 0.0.1 → 0.1.0

package/templates/stepper/index.tsx

@@ -0,0 +1,230 @@
+/**
+ * Stepper compound component exports.
+ *
+ * @example
+ * ```tsx
+ * import { Stepper } from "@/components/ui";
+ *
+ * <Stepper.Root value={2} onStepChange={(step) => console.log(step)}>
+ *   <Stepper.Item step={1} completed>
+ *     <Stepper.Trigger>
+ *       <Stepper.Indicator>1</Stepper.Indicator>
+ *       <Stepper.Title>Account</Stepper.Title>
+ *     </Stepper.Trigger>
+ *   </Stepper.Item>
+ *   <Stepper.Separator />
+ *   <Stepper.Item step={2}>
+ *     <Stepper.Trigger>
+ *       <Stepper.Indicator>2</Stepper.Indicator>
+ *       <Stepper.Title>Profile</Stepper.Title>
+ *     </Stepper.Trigger>
+ *   </Stepper.Item>
+ * </Stepper.Root>
+ * ```
+ */
+
+import {
+  type HTMLAttributes,
+  type ReactNode,
+  createElement,
+  forwardRef,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from "react";
+
+// ============================================================================
+// Types
+// ============================================================================
+
+export type StepperOrientation = "horizontal" | "vertical";
+
+export interface StepperRootProps extends HTMLAttributes<HTMLElement> {
+  children?: ReactNode;
+  value?: number;
+  defaultValue?: number;
+  onStepChange?: (step: number) => void;
+  orientation?: StepperOrientation;
+  linear?: boolean;
+}
+
+export interface StepperItemProps extends HTMLAttributes<HTMLElement> {
+  children?: ReactNode;
+  step: number;
+  completed?: boolean;
+  disabled?: boolean;
+}
+
+export interface StepperTriggerProps extends HTMLAttributes<HTMLElement> {
+  children?: ReactNode;
+}
+
+export interface StepperIndicatorProps extends HTMLAttributes<HTMLElement> {
+  children?: ReactNode;
+}
+
+export interface StepperTitleProps extends HTMLAttributes<HTMLElement> {
+  children?: ReactNode;
+}
+
+export interface StepperDescriptionProps extends HTMLAttributes<HTMLElement> {
+  children?: ReactNode;
+}
+
+export interface StepperSeparatorProps extends HTMLAttributes<HTMLElement> {}
+
+export interface StepperContentProps extends HTMLAttributes<HTMLElement> {
+  children?: ReactNode;
+}
+
+// ============================================================================
+// Components
+// ============================================================================
+
+const StepperRoot = forwardRef<HTMLElement, StepperRootProps>(function StepperRoot(
+  {
+    children,
+    className,
+    value: controlledValue,
+    defaultValue = 1,
+    onStepChange,
+    orientation = "horizontal",
+    linear = false,
+    ...props
+  },
+  ref
+) {
+  const [internalValue, setInternalValue] = useState(defaultValue);
+  const isControlled = controlledValue !== undefined;
+  const value = isControlled ? controlledValue : internalValue;
+  const elementRef = useRef<HTMLElement>(null);
+
+  const combinedRef = (node: HTMLElement | null) => {
+    (elementRef as React.MutableRefObject<HTMLElement | null>).current = node;
+    if (typeof ref === "function") ref(node);
+    else if (ref) (ref as React.MutableRefObject<HTMLElement | null>).current = node;
+  };
+
+  const handleStepChange = useCallback(
+    (event: Event) => {
+      const e = event as CustomEvent<{ step: number }>;
+      if (!isControlled) setInternalValue(e.detail.step);
+      onStepChange?.(e.detail.step);
+    },
+    [isControlled, onStepChange]
+  );
+
+  useEffect(() => {
+    const element = elementRef.current;
+    if (!element) return;
+    element.addEventListener("ds:step-change", handleStepChange);
+    return () => element.removeEventListener("ds:step-change", handleStepChange);
+  }, [handleStepChange]);
+
+  return createElement(
+    "ds-stepper",
+    {
+      ref: combinedRef,
+      class: className,
+      value,
+      orientation,
+      linear: linear || undefined,
+      ...props,
+    },
+    children
+  );
+});
+StepperRoot.displayName = "Stepper.Root";
+
+const StepperItem = forwardRef<HTMLElement, StepperItemProps>(function StepperItem(
+  { children, className, step, completed, disabled, ...props },
+  ref
+) {
+  return createElement(
+    "ds-stepper-item",
+    {
+      ref,
+      class: className,
+      step,
+      completed: completed || undefined,
+      disabled: disabled || undefined,
+      ...props,
+    },
+    children
+  );
+});
+StepperItem.displayName = "Stepper.Item";
+
+const StepperTrigger = forwardRef<HTMLElement, StepperTriggerProps>(function StepperTrigger(
+  { children, className, ...props },
+  ref
+) {
+  return createElement("ds-stepper-trigger", { ref, class: className, ...props }, children);
+});
+StepperTrigger.displayName = "Stepper.Trigger";
+
+const StepperIndicator = forwardRef<HTMLElement, StepperIndicatorProps>(function StepperIndicator(
+  { children, className, ...props },
+  ref
+) {
+  return createElement("ds-stepper-indicator", { ref, class: className, ...props }, children);
+});
+StepperIndicator.displayName = "Stepper.Indicator";
+
+const StepperTitle = forwardRef<HTMLElement, StepperTitleProps>(function StepperTitle(
+  { children, className, ...props },
+  ref
+) {
+  return createElement("ds-stepper-title", { ref, class: className, ...props }, children);
+});
+StepperTitle.displayName = "Stepper.Title";
+
+const StepperDescription = forwardRef<HTMLElement, StepperDescriptionProps>(
+  function StepperDescription({ children, className, ...props }, ref) {
+    return createElement("ds-stepper-description", { ref, class: className, ...props }, children);
+  }
+);
+StepperDescription.displayName = "Stepper.Description";
+
+const StepperSeparator = forwardRef<HTMLElement, StepperSeparatorProps>(function StepperSeparator(
+  { className, ...props },
+  ref
+) {
+  return createElement("ds-stepper-separator", { ref, class: className, ...props });
+});
+StepperSeparator.displayName = "Stepper.Separator";
+
+const StepperContent = forwardRef<HTMLElement, StepperContentProps>(function StepperContent(
+  { children, className, ...props },
+  ref
+) {
+  return createElement("ds-stepper-content", { ref, class: className, ...props }, children);
+});
+StepperContent.displayName = "Stepper.Content";
+
+// ============================================================================
+// Compound Component
+// ============================================================================
+
+export const Stepper = {
+  Root: StepperRoot,
+  Item: StepperItem,
+  Trigger: StepperTrigger,
+  Indicator: StepperIndicator,
+  Title: StepperTitle,
+  Description: StepperDescription,
+  Separator: StepperSeparator,
+  Content: StepperContent,
+};
+
+export {
+  StepperRoot,
+  StepperItem,
+  StepperTrigger,
+  StepperIndicator,
+  StepperTitle,
+  StepperDescription,
+  StepperSeparator,
+  StepperContent,
+};

package/templates/stepper/wc/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Stepper component exports.
+ */
+
+export { DsStepper, type StepperOrientation } from "./stepper.js";
+export { DsStepperItem } from "./stepper-item.js";
+export { DsStepperTrigger } from "./stepper-trigger.js";
+export { DsStepperIndicator } from "./stepper-indicator.js";
+export { DsStepperTitle } from "./stepper-title.js";
+export { DsStepperDescription } from "./stepper-description.js";
+export { DsStepperSeparator } from "./stepper-separator.js";
+export { DsStepperContent } from "./stepper-content.js";

package/templates/stepper/wc/stepper-content.ts

@@ -0,0 +1,30 @@
+/**
+ * StepperContent component - step panel content.
+ *
+ * @element ds-stepper-content
+ *
+ * @slot - Step content
+ */
+
+import { html } from "lit";
+import { DSElement } from "../../base/ds-element.js";
+import { define } from "../../registry/define.js";
+
+export class DsStepperContent extends DSElement {
+  override connectedCallback(): void {
+    super.connectedCallback();
+    this.setAttribute("role", "tabpanel");
+  }
+
+  override render() {
+    return html`<slot></slot>`;
+  }
+}
+
+define("ds-stepper-content", DsStepperContent);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "ds-stepper-content": DsStepperContent;
+  }
+}

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

@@ -0,0 +1,25 @@
+/**
+ * StepperDescription component - optional step description.
+ *
+ * @element ds-stepper-description
+ *
+ * @slot - Description text
+ */
+
+import { html } from "lit";
+import { DSElement } from "../../base/ds-element.js";
+import { define } from "../../registry/define.js";
+
+export class DsStepperDescription extends DSElement {
+  override render() {
+    return html`<slot></slot>`;
+  }
+}
+
+define("ds-stepper-description", DsStepperDescription);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "ds-stepper-description": DsStepperDescription;
+  }
+}

package/templates/stepper/wc/stepper-indicator.ts

@@ -0,0 +1,30 @@
+/**
+ * StepperIndicator component - visual step number/icon.
+ *
+ * @element ds-stepper-indicator
+ *
+ * @slot - Step number or icon
+ */
+
+import { html } from "lit";
+import { DSElement } from "../../base/ds-element.js";
+import { define } from "../../registry/define.js";
+
+export class DsStepperIndicator extends DSElement {
+  override connectedCallback(): void {
+    super.connectedCallback();
+    this.setAttribute("aria-hidden", "true");
+  }
+
+  override render() {
+    return html`<slot></slot>`;
+  }
+}
+
+define("ds-stepper-indicator", DsStepperIndicator);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "ds-stepper-indicator": DsStepperIndicator;
+  }
+}

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

@@ -0,0 +1,55 @@
+/**
+ * StepperItem component - individual step container.
+ *
+ * @element ds-stepper-item
+ *
+ * @slot - Trigger and content
+ */
+
+import { html } from "lit";
+import { property } from "lit/decorators.js";
+import { DSElement } from "../../base/ds-element.js";
+import { define } from "../../registry/define.js";
+
+export class DsStepperItem extends DSElement {
+  /** Step number (1-indexed) */
+  @property({ type: Number, reflect: true })
+  step = 1;
+
+  /** Whether this step is completed */
+  @property({ type: Boolean, reflect: true })
+  completed = false;
+
+  /** Whether this step is disabled */
+  @property({ type: Boolean, reflect: true })
+  disabled = false;
+
+  override connectedCallback(): void {
+    super.connectedCallback();
+    this.setAttribute("role", "listitem");
+    this.setAttribute("data-state", "pending");
+  }
+
+  override updated(_changedProperties: Map<string, unknown>): void {
+    // Update aria-current when state changes
+    // Per APG, aria-current="step" indicates the current step in a process
+    const state = this.getAttribute("data-state");
+    if (state === "active") {
+      this.setAttribute("aria-current", "step");
+    } else {
+      this.removeAttribute("aria-current");
+    }
+  }
+
+  override render() {
+    return html`<slot></slot>`;
+  }
+}
+
+define("ds-stepper-item", DsStepperItem);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "ds-stepper-item": DsStepperItem;
+  }
+}

package/templates/stepper/wc/stepper-separator.ts

@@ -0,0 +1,29 @@
+/**
+ * StepperSeparator component - line between steps.
+ *
+ * @element ds-stepper-separator
+ */
+
+import { html } from "lit";
+import { DSElement } from "../../base/ds-element.js";
+import { define } from "../../registry/define.js";
+
+export class DsStepperSeparator extends DSElement {
+  override connectedCallback(): void {
+    super.connectedCallback();
+    this.setAttribute("role", "separator");
+    this.setAttribute("aria-hidden", "true");
+  }
+
+  override render() {
+    return html``;
+  }
+}
+
+define("ds-stepper-separator", DsStepperSeparator);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "ds-stepper-separator": DsStepperSeparator;
+  }
+}

package/templates/stepper/wc/stepper-title.ts

@@ -0,0 +1,25 @@
+/**
+ * StepperTitle component - step title text.
+ *
+ * @element ds-stepper-title
+ *
+ * @slot - Title text
+ */
+
+import { html } from "lit";
+import { DSElement } from "../../base/ds-element.js";
+import { define } from "../../registry/define.js";
+
+export class DsStepperTitle extends DSElement {
+  override render() {
+    return html`<slot></slot>`;
+  }
+}
+
+define("ds-stepper-title", DsStepperTitle);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "ds-stepper-title": DsStepperTitle;
+  }
+}

package/templates/stepper/wc/stepper-trigger.ts

@@ -0,0 +1,67 @@
+/**
+ * StepperTrigger component - clickable step button.
+ *
+ * @element ds-stepper-trigger
+ *
+ * @slot - Indicator and title
+ */
+
+import { html } from "lit";
+import { DSElement } from "../../base/ds-element.js";
+import { emitEvent } from "../../events/emit.js";
+import { define } from "../../registry/define.js";
+
+export class DsStepperTrigger extends DSElement {
+  override connectedCallback(): void {
+    super.connectedCallback();
+    this.setAttribute("role", "button");
+    this.setAttribute("tabindex", "0");
+
+    this.addEventListener("click", this.handleClick);
+    this.addEventListener("keydown", this.handleKeyDown);
+  }
+
+  override disconnectedCallback(): void {
+    super.disconnectedCallback();
+    this.removeEventListener("click", this.handleClick);
+    this.removeEventListener("keydown", this.handleKeyDown);
+  }
+
+  private getStep(): number {
+    const item = this.closest("ds-stepper-item");
+    return Number(item?.getAttribute("step")) || 1;
+  }
+
+  private isDisabled(): boolean {
+    const item = this.closest("ds-stepper-item");
+    return item?.hasAttribute("disabled") || false;
+  }
+
+  private handleClick = (): void => {
+    if (this.isDisabled()) return;
+
+    emitEvent(this, "ds:step-select", {
+      detail: { step: this.getStep() },
+      bubbles: true,
+    });
+  };
+
+  private handleKeyDown = (event: KeyboardEvent): void => {
+    if (event.key === "Enter" || event.key === " ") {
+      event.preventDefault();
+      this.handleClick();
+    }
+  };
+
+  override render() {
+    return html`<slot></slot>`;
+  }
+}
+
+define("ds-stepper-trigger", DsStepperTrigger);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "ds-stepper-trigger": DsStepperTrigger;
+  }
+}

package/templates/stepper/wc/stepper.ts

@@ -0,0 +1,164 @@
+/**
+ * Stepper component - step-by-step progress indicator.
+ *
+ * @element ds-stepper
+ *
+ * @slot - Stepper items
+ *
+ * @fires ds:step-change - Fired when active step changes
+ *
+ * @example
+ * ```html
+ * <ds-stepper value="2">
+ *   <ds-stepper-item step="1" completed>
+ *     <ds-stepper-trigger>
+ *       <ds-stepper-indicator>1</ds-stepper-indicator>
+ *       <ds-stepper-title>Account</ds-stepper-title>
+ *     </ds-stepper-trigger>
+ *   </ds-stepper-item>
+ *   <ds-stepper-separator></ds-stepper-separator>
+ *   <ds-stepper-item step="2">
+ *     <ds-stepper-trigger>
+ *       <ds-stepper-indicator>2</ds-stepper-indicator>
+ *       <ds-stepper-title>Profile</ds-stepper-title>
+ *     </ds-stepper-trigger>
+ *   </ds-stepper-item>
+ * </ds-stepper>
+ * ```
+ */
+
+import { html } from "lit";
+import { property } from "lit/decorators.js";
+import { DSElement } from "../../base/ds-element.js";
+import { emitEvent } from "../../events/emit.js";
+import { define } from "../../registry/define.js";
+
+// Import child components
+import "./stepper-item.js";
+import "./stepper-trigger.js";
+import "./stepper-indicator.js";
+import "./stepper-title.js";
+import "./stepper-description.js";
+import "./stepper-separator.js";
+import "./stepper-content.js";
+
+export type StepperOrientation = "horizontal" | "vertical";
+
+export class DsStepper extends DSElement {
+  /** Current step value */
+  @property({ type: Number, reflect: true })
+  value = 1;
+
+  /** Orientation */
+  @property({ type: String, reflect: true })
+  orientation: StepperOrientation = "horizontal";
+
+  /** Whether steps are linear (must complete in order) */
+  @property({ type: Boolean })
+  linear = false;
+
+  /**
+   * Accessible label for the stepper.
+   * Per APG, the stepper should have a clear label describing its purpose.
+   */
+  @property({ type: String, attribute: "aria-label" })
+  override ariaLabel = "Progress steps";
+
+  override connectedCallback(): void {
+    super.connectedCallback();
+    // Use role="list" for ordered sequence of steps per APG
+    // Combined with aria-current="step" on active item for process indication
+    this.setAttribute("role", "list");
+    this.setAttribute("aria-label", this.ariaLabel);
+
+    this.addEventListener("ds:step-select", this.handleStepSelect as EventListener);
+  }
+
+  override disconnectedCallback(): void {
+    super.disconnectedCallback();
+    this.removeEventListener("ds:step-select", this.handleStepSelect as EventListener);
+  }
+
+  /**
+   * Go to a specific step.
+   */
+  public goToStep(step: number): void {
+    if (this.linear) {
+      // In linear mode, can only go to completed steps or next step
+      const items = this.querySelectorAll("ds-stepper-item");
+      let maxAllowed = 1;
+
+      for (const item of items) {
+        const itemStep = Number(item.getAttribute("step"));
+        if (item.hasAttribute("completed") || itemStep === this.value) {
+          maxAllowed = Math.max(maxAllowed, itemStep + 1);
+        }
+      }
+
+      if (step > maxAllowed) return;
+    }
+
+    if (step !== this.value) {
+      this.value = step;
+      this.updateActiveState();
+
+      emitEvent(this, "ds:step-change", {
+        detail: { step: this.value },
+        bubbles: true,
+      });
+    }
+  }
+
+  /**
+   * Go to next step.
+   */
+  public nextStep(): void {
+    this.goToStep(this.value + 1);
+  }
+
+  /**
+   * Go to previous step.
+   */
+  public previousStep(): void {
+    this.goToStep(this.value - 1);
+  }
+
+  private handleStepSelect = (event: CustomEvent<{ step: number }>): void => {
+    event.stopPropagation();
+    this.goToStep(event.detail.step);
+  };
+
+  private updateActiveState(): void {
+    const items = this.querySelectorAll("ds-stepper-item");
+
+    for (const item of items) {
+      const step = Number(item.getAttribute("step"));
+
+      if (step === this.value) {
+        item.setAttribute("data-state", "active");
+      } else if (step < this.value || item.hasAttribute("completed")) {
+        item.setAttribute("data-state", "completed");
+      } else {
+        item.setAttribute("data-state", "pending");
+      }
+    }
+  }
+
+  override updated(changedProperties: Map<string, unknown>): void {
+    if (changedProperties.has("value")) {
+      this.updateActiveState();
+    }
+  }
+
+  override render() {
+    return html`<slot></slot>`;
+  }
+}
+
+define("ds-stepper", DsStepper);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "ds-stepper": DsStepper;
+  }
+}