@hypoth-ui/cli 0.0.1 → 0.1.0

package/templates/select/select-context.ts

@@ -0,0 +1,30 @@
+/**
+ * Select context for compound component pattern.
+ */
+
+import type { SelectBehavior } from "@hypoth-ui/primitives-dom";
+import { createCompoundContext } from "../../utils/create-context.js";
+
+export interface SelectContextValue {
+  /** Select behavior instance */
+  behavior: SelectBehavior<string>;
+  /** Whether select is open */
+  open: boolean;
+  /** Set open state */
+  setOpen: (open: boolean) => void;
+  /** Current value */
+  value: string | null;
+  /** Set value */
+  setValue: (value: string | null) => void;
+  /** Highlighted value for keyboard navigation */
+  highlightedValue: string | null;
+  /** Set highlighted value */
+  setHighlightedValue: (value: string | null) => void;
+  /** Whether the select is in a loading state */
+  loading: boolean;
+  /** Text to display during loading */
+  loadingText: string;
+}
+
+export const [SelectProvider, useSelectContext] =
+  createCompoundContext<SelectContextValue>("Select");

package/templates/select/select-group.tsx

@@ -0,0 +1,53 @@
+/**
+ * Select Group component - groups options with an optional label.
+ */
+
+import { type HTMLAttributes, type ReactNode, forwardRef, useId } from "react";
+
+export interface SelectGroupProps extends HTMLAttributes<HTMLFieldSetElement> {
+  /** Group content (Label and Options) */
+  children?: ReactNode;
+  /** Optional label text (alternative to using Select.Label as child) */
+  label?: string;
+}
+
+/**
+ * Group for organizing select options.
+ *
+ * @example
+ * ```tsx
+ * <Select.Content>
+ *   <Select.Group>
+ *     <Select.Label>Fruits</Select.Label>
+ *     <Select.Option value="apple">Apple</Select.Option>
+ *     <Select.Option value="banana">Banana</Select.Option>
+ *   </Select.Group>
+ *   <Select.Group label="Vegetables">
+ *     <Select.Option value="carrot">Carrot</Select.Option>
+ *     <Select.Option value="potato">Potato</Select.Option>
+ *   </Select.Group>
+ * </Select.Content>
+ * ```
+ */
+export const SelectGroup = forwardRef<HTMLFieldSetElement, SelectGroupProps>(
+  ({ children, className, label, ...restProps }, ref) => {
+    const groupId = useId();
+    const labelId = `${groupId}-label`;
+
+    return (
+      <fieldset
+        ref={ref}
+        aria-label={label}
+        aria-labelledby={!label ? labelId : undefined}
+        className={className}
+        data-group-label-id={labelId}
+        {...restProps}
+      >
+        {label && <legend className="sr-only">{label}</legend>}
+        {children}
+      </fieldset>
+    );
+  }
+);
+
+SelectGroup.displayName = "Select.Group";

package/templates/select/select-label.tsx

@@ -0,0 +1,34 @@
+/**
+ * Select Label component - label for option groups.
+ */
+
+import { type HTMLAttributes, type ReactNode, forwardRef } from "react";
+
+export interface SelectLabelProps extends HTMLAttributes<HTMLDivElement> {
+  /** Label content */
+  children?: ReactNode;
+}
+
+/**
+ * Label for grouping options.
+ *
+ * @example
+ * ```tsx
+ * <Select.Content>
+ *   <Select.Label>Fruits</Select.Label>
+ *   <Select.Option value="apple">Apple</Select.Option>
+ *   <Select.Option value="banana">Banana</Select.Option>
+ * </Select.Content>
+ * ```
+ */
+export const SelectLabel = forwardRef<HTMLDivElement, SelectLabelProps>(
+  ({ children, className, ...restProps }, ref) => {
+    return (
+      <div ref={ref} role="presentation" aria-hidden="true" className={className} {...restProps}>
+        {children}
+      </div>
+    );
+  }
+);
+
+SelectLabel.displayName = "Select.Label";

package/templates/select/select-option.tsx

@@ -0,0 +1,97 @@
+/**
+ * Select Option component - individual option in the select.
+ */
+
+import { type HTMLAttributes, type ReactNode, forwardRef, useCallback } from "react";
+import { useSelectContext } from "./select-context.js";
+
+export interface SelectOptionProps extends Omit<HTMLAttributes<HTMLDivElement>, "value"> {
+  /** Option value */
+  value: string;
+  /** Display label (uses children if not specified) */
+  label?: string;
+  /** Whether the option is disabled */
+  disabled?: boolean;
+  /** Option content */
+  children?: ReactNode;
+}
+
+/**
+ * Individual option in the select.
+ *
+ * @example
+ * ```tsx
+ * <Select.Option value="apple">Apple</Select.Option>
+ * <Select.Option value="banana" disabled>Banana</Select.Option>
+ * ```
+ */
+export const SelectOption = forwardRef<HTMLDivElement, SelectOptionProps>(
+  (
+    {
+      value: optionValue,
+      label,
+      disabled = false,
+      children,
+      className,
+      onClick,
+      onMouseEnter,
+      ...restProps
+    },
+    ref
+  ) => {
+    const { behavior, value, highlightedValue, setHighlightedValue, setOpen } =
+      useSelectContext("Select.Option");
+
+    const isSelected = value === optionValue;
+    const isHighlighted = highlightedValue === optionValue;
+
+    // Handle click to select
+    const handleClick = useCallback(
+      (event: React.MouseEvent<HTMLDivElement>) => {
+        if (disabled) return;
+        behavior.select(optionValue);
+        setOpen(false);
+        onClick?.(event);
+      },
+      [behavior, optionValue, disabled, setOpen, onClick]
+    );
+
+    // Handle mouse enter to highlight
+    const handleMouseEnter = useCallback(
+      (event: React.MouseEvent<HTMLDivElement>) => {
+        if (disabled) return;
+        behavior.highlight(optionValue);
+        setHighlightedValue(optionValue);
+        onMouseEnter?.(event);
+      },
+      [behavior, optionValue, disabled, setHighlightedValue, onMouseEnter]
+    );
+
+    const optionProps = behavior.getOptionProps(
+      optionValue,
+      label || String(children) || optionValue
+    );
+
+    return (
+      <div
+        ref={ref}
+        role={optionProps.role}
+        id={optionProps.id}
+        aria-selected={isSelected}
+        aria-disabled={disabled || undefined}
+        data-value={optionValue}
+        data-selected={isSelected || undefined}
+        data-highlighted={isHighlighted || undefined}
+        data-disabled={disabled || undefined}
+        className={className}
+        onClick={handleClick}
+        onMouseEnter={handleMouseEnter}
+        {...restProps}
+      >
+        {children}
+      </div>
+    );
+  }
+);
+
+SelectOption.displayName = "Select.Option";

package/templates/select/select-root.tsx

@@ -0,0 +1,153 @@
+/**
+ * Select Root component - provides context to all Select compound components.
+ */
+
+import { type Placement, createSelectBehavior } from "@hypoth-ui/primitives-dom";
+import { type ReactNode, useCallback, useMemo, useState } from "react";
+import { useStableId } from "../../hooks/use-stable-id.js";
+import { SelectProvider } from "./select-context.js";
+
+export interface SelectRootProps {
+  /** Select content */
+  children?: ReactNode;
+  /** Custom ID for the select (SSR-safe auto-generated if not provided) */
+  id?: string;
+  /** Controlled open state */
+  open?: boolean;
+  /** Default open state (uncontrolled) */
+  defaultOpen?: boolean;
+  /** Called when open state changes */
+  onOpenChange?: (open: boolean) => void;
+  /** Controlled value */
+  value?: string | null;
+  /** Default value (uncontrolled) */
+  defaultValue?: string | null;
+  /** Called when value changes */
+  onValueChange?: (value: string | null) => void;
+  /** Placement relative to trigger */
+  placement?: Placement;
+  /** Offset from trigger in pixels */
+  offset?: number;
+  /** Whether to flip placement on viewport edge */
+  flip?: boolean;
+  /** Whether select is disabled */
+  disabled?: boolean;
+  /** Whether select is read-only */
+  readOnly?: boolean;
+  /** Enable typeahead search */
+  searchable?: boolean;
+  /** Allow clearing the selection */
+  clearable?: boolean;
+  /** Whether the select is in a loading state (e.g., fetching options) */
+  loading?: boolean;
+  /** Text to display/announce during loading */
+  loadingText?: string;
+}
+
+/**
+ * Root component for Select compound pattern.
+ * Provides context to Trigger, Content, and Option.
+ *
+ * @example
+ * ```tsx
+ * <Select.Root onValueChange={(value) => console.log(value)}>
+ *   <Select.Trigger>Select a fruit</Select.Trigger>
+ *   <Select.Content>
+ *     <Select.Option value="apple">Apple</Select.Option>
+ *     <Select.Option value="banana">Banana</Select.Option>
+ *   </Select.Content>
+ * </Select.Root>
+ * ```
+ */
+export function SelectRoot({
+  children,
+  id,
+  open: controlledOpen,
+  defaultOpen = false,
+  onOpenChange,
+  value: controlledValue,
+  defaultValue = null,
+  onValueChange,
+  placement: _placement = "bottom-start",
+  offset: _offset = 4,
+  flip: _flip = true,
+  disabled = false,
+  readOnly = false,
+  searchable = true,
+  clearable = false,
+  loading = false,
+  loadingText = "Loading...",
+}: SelectRootProps) {
+  // Generate SSR-safe stable ID using React 18's useId under the hood
+  const stableId = useStableId({ id, prefix: "select" });
+
+  // Support both controlled and uncontrolled modes for open
+  const [internalOpen, setInternalOpen] = useState(defaultOpen);
+  const isOpenControlled = controlledOpen !== undefined;
+  const open = isOpenControlled ? controlledOpen : internalOpen;
+
+  // Support both controlled and uncontrolled modes for value
+  const [internalValue, setInternalValue] = useState<string | null>(defaultValue);
+  const isValueControlled = controlledValue !== undefined;
+  const value = isValueControlled ? controlledValue : internalValue;
+
+  // Highlighted value for keyboard navigation
+  const [highlightedValue, setHighlightedValue] = useState<string | null>(value);
+
+  const setOpen = useCallback(
+    (nextOpen: boolean) => {
+      if (!isOpenControlled) {
+        setInternalOpen(nextOpen);
+      }
+      onOpenChange?.(nextOpen);
+    },
+    [isOpenControlled, onOpenChange]
+  );
+
+  const setValue = useCallback(
+    (nextValue: string | null) => {
+      if (!isValueControlled) {
+        setInternalValue(nextValue);
+      }
+      onValueChange?.(nextValue);
+    },
+    [isValueControlled, onValueChange]
+  );
+
+  // Create behavior instance - intentionally created once with initial values
+  // biome-ignore lint/correctness/useExhaustiveDependencies: behavior is created once, state synced via callbacks
+  const behavior = useMemo(
+    () =>
+      createSelectBehavior({
+        defaultValue: value,
+        disabled,
+        readOnly,
+        searchable,
+        clearable,
+        onValueChange: (v) => setValue(v),
+        onOpenChange: (o) => setOpen(o),
+        // Use SSR-safe stable ID generator
+        generateId: () => stableId,
+      }),
+    [stableId]
+  );
+
+  const contextValue = useMemo(
+    () => ({
+      behavior,
+      open,
+      setOpen,
+      value,
+      setValue,
+      highlightedValue,
+      setHighlightedValue,
+      loading,
+      loadingText,
+    }),
+    [behavior, open, setOpen, value, setValue, highlightedValue, loading, loadingText]
+  );
+
+  return <SelectProvider value={contextValue}>{children}</SelectProvider>;
+}
+
+SelectRoot.displayName = "Select.Root";

package/templates/select/select-separator.tsx

@@ -0,0 +1,27 @@
+/**
+ * Select Separator component - visual separator between groups.
+ */
+
+import { type HTMLAttributes, forwardRef } from "react";
+
+export interface SelectSeparatorProps extends HTMLAttributes<HTMLHRElement> {}
+
+/**
+ * Visual separator for grouping options.
+ *
+ * @example
+ * ```tsx
+ * <Select.Content>
+ *   <Select.Option value="apple">Apple</Select.Option>
+ *   <Select.Separator />
+ *   <Select.Option value="banana">Banana</Select.Option>
+ * </Select.Content>
+ * ```
+ */
+export const SelectSeparator = forwardRef<HTMLHRElement, SelectSeparatorProps>(
+  ({ className, ...restProps }, ref) => {
+    return <hr ref={ref} className={className} {...restProps} />;
+  }
+);
+
+SelectSeparator.displayName = "Select.Separator";

package/templates/select/select-trigger.tsx

@@ -0,0 +1,112 @@
+/**
+ * Select Trigger component - opens the select when activated.
+ */
+
+import { type ButtonHTMLAttributes, type ReactNode, forwardRef, useCallback, useRef } from "react";
+import { Slot } from "../../primitives/slot.js";
+import { useSelectContext } from "./select-context.js";
+
+export interface SelectTriggerProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  /** Trigger content */
+  children?: ReactNode;
+  /** Render as child element (polymorphic) */
+  asChild?: boolean;
+}
+
+/**
+ * Trigger button that opens the select.
+ * Supports asChild for custom trigger elements.
+ *
+ * @example
+ * ```tsx
+ * <Select.Trigger>Select a fruit</Select.Trigger>
+ *
+ * <Select.Trigger asChild>
+ *   <button className="custom-button">Custom Trigger</button>
+ * </Select.Trigger>
+ * ```
+ */
+export const SelectTrigger = forwardRef<HTMLButtonElement, SelectTriggerProps>(
+  ({ children, asChild = false, onClick, onKeyDown, ...restProps }, ref) => {
+    const { behavior, open, highlightedValue } = useSelectContext("Select.Trigger");
+    const internalRef = useRef<HTMLButtonElement>(null);
+
+    // Handle click to toggle select
+    const handleClick = useCallback(
+      (event: React.MouseEvent<HTMLButtonElement>) => {
+        behavior.toggle();
+        onClick?.(event);
+      },
+      [behavior, onClick]
+    );
+
+    // Handle keyboard navigation
+    const handleKeyDown = useCallback(
+      (event: React.KeyboardEvent<HTMLButtonElement>) => {
+        switch (event.key) {
+          case "Enter":
+          case " ":
+            event.preventDefault();
+            behavior.toggle();
+            break;
+          case "ArrowDown":
+            event.preventDefault();
+            if (!open) {
+              behavior.open();
+              behavior.highlightFirst();
+            }
+            break;
+          case "ArrowUp":
+            event.preventDefault();
+            if (!open) {
+              behavior.open();
+              behavior.highlightLast();
+            }
+            break;
+        }
+        onKeyDown?.(event);
+      },
+      [behavior, open, onKeyDown]
+    );
+
+    // Get trigger props from behavior
+    const triggerProps = behavior.getTriggerProps();
+
+    const Component = asChild ? Slot : "button";
+
+    // Merge refs
+    const mergedRef = useCallback(
+      (element: HTMLButtonElement | null) => {
+        (internalRef as React.MutableRefObject<HTMLButtonElement | null>).current = element;
+        if (typeof ref === "function") {
+          ref(element);
+        } else if (ref) {
+          (ref as React.MutableRefObject<HTMLButtonElement | null>).current = element;
+        }
+      },
+      [ref]
+    );
+
+    return (
+      <Component
+        ref={mergedRef}
+        type={asChild ? undefined : "button"}
+        role={triggerProps.role}
+        aria-haspopup={triggerProps["aria-haspopup"]}
+        aria-expanded={open}
+        aria-controls={behavior.contentId}
+        aria-activedescendant={
+          open && highlightedValue ? `select-option-${highlightedValue}` : undefined
+        }
+        onClick={handleClick}
+        onKeyDown={handleKeyDown}
+        data-state={open ? "open" : "closed"}
+        {...restProps}
+      >
+        {children}
+      </Component>
+    );
+  }
+);
+
+SelectTrigger.displayName = "Select.Trigger";

package/templates/select/select-value.tsx

@@ -0,0 +1,48 @@
+/**
+ * Select Value component - displays the selected value.
+ */
+
+import { type HTMLAttributes, type ReactNode, forwardRef } from "react";
+import { useSelectContext } from "./select-context.js";
+
+export interface SelectValueProps extends Omit<HTMLAttributes<HTMLSpanElement>, "children"> {
+  /** Placeholder text when no value is selected */
+  placeholder?: string;
+  /** Custom render function for the value */
+  children?: ReactNode | ((value: string | null) => ReactNode);
+}
+
+/**
+ * Displays the currently selected value.
+ * Used inside Select.Trigger.
+ *
+ * @example
+ * ```tsx
+ * <Select.Trigger>
+ *   <Select.Value placeholder="Select a fruit" />
+ * </Select.Trigger>
+ * ```
+ */
+export const SelectValue = forwardRef<HTMLSpanElement, SelectValueProps>(
+  ({ placeholder, children, className, ...restProps }, ref) => {
+    const { value } = useSelectContext("Select.Value");
+
+    let displayContent: ReactNode;
+
+    if (typeof children === "function") {
+      displayContent = children(value);
+    } else if (children) {
+      displayContent = value ? children : placeholder;
+    } else {
+      displayContent = value || placeholder;
+    }
+
+    return (
+      <span ref={ref} className={className} data-placeholder={!value || undefined} {...restProps}>
+        {displayContent}
+      </span>
+    );
+  }
+);
+
+SelectValue.displayName = "Select.Value";

package/templates/select/wc/index.ts

@@ -0,0 +1,6 @@
+export { DsSelect } from "./select.js";
+export { DsSelectTrigger } from "./select-trigger.js";
+export { DsSelectContent, type SelectContentState } from "./select-content.js";
+export { DsSelectOption } from "./select-option.js";
+export { DsSelectGroup } from "./select-group.js";
+export { DsSelectLabel } from "./select-label.js";

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

@@ -0,0 +1,89 @@
+import { html } from "lit";
+import { property } from "lit/decorators.js";
+import { DSElement } from "../../base/ds-element.js";
+import { define } from "../../registry/define.js";
+
+export type SelectContentState = "open" | "closed";
+
+/**
+ * Select content container with role="listbox".
+ *
+ * @element ds-select-content
+ *
+ * @slot - Select options (ds-select-option elements)
+ *
+ * @attr {string} data-state - Animation state ("open" or "closed")
+ * @attr {string} data-placement - Current anchor position placement
+ *
+ * @example
+ * ```html
+ * <ds-select>
+ *   <button slot="trigger">Select fruit</button>
+ *   <ds-select-content>
+ *     <ds-select-option value="apple">Apple</ds-select-option>
+ *     <ds-select-option value="banana">Banana</ds-select-option>
+ *   </ds-select-content>
+ * </ds-select>
+ * ```
+ */
+export class DsSelectContent extends DSElement {
+  /** Unique ID for ARIA association */
+  @property({ type: String, reflect: true })
+  override id = "";
+
+  /** Animation state (open or closed) - set by parent ds-select */
+  @property({ type: String, reflect: true, attribute: "data-state" })
+  dataState: SelectContentState = "closed";
+
+  /** Optional label for the listbox */
+  @property({ type: String })
+  label = "";
+
+  override connectedCallback(): void {
+    super.connectedCallback();
+
+    // Generate ID if not set
+    if (!this.id) {
+      this.id = `select-content-${crypto.randomUUID().slice(0, 8)}`;
+    }
+
+    // Set ARIA role for listbox
+    this.setAttribute("role", "listbox");
+
+    // Set label if provided
+    if (this.label) {
+      this.setAttribute("aria-label", this.label);
+    }
+
+    // Hidden by default (parent select controls visibility)
+    this.setAttribute("hidden", "");
+  }
+
+  override updated(changedProperties: Map<string, unknown>): void {
+    super.updated(changedProperties);
+
+    if (changedProperties.has("label")) {
+      if (this.label) {
+        this.setAttribute("aria-label", this.label);
+      } else {
+        this.removeAttribute("aria-label");
+      }
+    }
+  }
+
+  override render() {
+    return html`
+      <div class="ds-select-content" part="container">
+        <slot></slot>
+      </div>
+    `;
+  }
+}
+
+define("ds-select-content", DsSelectContent);
+
+declare global {
+  interface HTMLElementTagNameMap {
+    "ds-select-content": DsSelectContent;
+  }
+}