@hypoth-ui/cli 0.1.0 → 0.1.2

package/dist/{add-V5PW73GC.js → add-SZWOYJL5.js}

@@ -21,7 +21,7 @@ import * as p from "@clack/prompts";
 import pc from "picocolors";
 
 // src/utils/copy.ts
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from "fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "fs";
 import { dirname, join } from "path";
 async function copyComponentFiles(component, config, options = {}) {
   const { cwd = process.cwd(), overwrite = false, sourceDir } = options;
@@ -32,6 +32,7 @@ async function copyComponentFiles(component, config, options = {}) {
     skipped: [],
     errors: []
   };
+  copySharedFiles(targetDir, overwrite);
   for (const file of files) {
     const targetPath = join(targetDir, component.name, file.target);
     if (existsSync(targetPath) && !overwrite) {
@@ -91,6 +92,28 @@ function getBundledTemplatePath(componentName, filePath) {
   const __dirname2 = new URL(".", import.meta.url).pathname;
   return join(__dirname2, "../../templates", componentName, filePath);
 }
+function copySharedFiles(targetDir, overwrite) {
+  const __dirname2 = new URL(".", import.meta.url).pathname;
+  const sharedSourceDir = join(__dirname2, "../../templates/_shared");
+  if (!existsSync(sharedSourceDir)) {
+    return;
+  }
+  function copyDir(srcDir, destDir) {
+    if (!existsSync(destDir)) {
+      mkdirSync(destDir, { recursive: true });
+    }
+    for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
+      const srcPath = join(srcDir, entry.name);
+      const destPath = join(destDir, entry.name);
+      if (entry.isDirectory()) {
+        copyDir(srcPath, destPath);
+      } else if (!existsSync(destPath) || overwrite) {
+        writeFileSync(destPath, readFileSync(srcPath, "utf-8"), "utf-8");
+      }
+    }
+  }
+  copyDir(sharedSourceDir, join(targetDir, "_shared"));
+}
 function transformImports(content, config, fileType) {
   if (fileType !== "ts" && fileType !== "tsx") {
     return content;

package/dist/index.js

@@ -10,7 +10,7 @@ program.command("init").description("Initialize hypoth-ui in your project").opti
   await initCommand(options);
 });
 program.command("add").description("Add components to your project").argument("[components...]", "Component names to add").option("-c, --copy", "Copy component source files instead of installing package").option("-o, --overwrite", "Overwrite existing components").option("-a, --all", "Add all available components").action(async (components, options) => {
-  const { addCommand } = await import("./add-V5PW73GC.js");
+  const { addCommand } = await import("./add-SZWOYJL5.js");
   await addCommand(components, options);
 });
 program.command("list").description("List available components").option("-j, --json", "Output as JSON").action(async (options) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hypoth-ui/cli",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "CLI tool for adding hypoth-ui components to your project (Alpha)",
   "homepage": "https://github.com/hypoth-ui/hypoth-ui#readme",
   "type": "module",

package/templates/_shared/hooks/use-responsive-classes.ts

@@ -0,0 +1,92 @@
+/**
+ * React Responsive Classes Hook
+ *
+ * Converts React responsive object syntax to CSS classes.
+ * React syntax: { base: "column", md: "row" }
+ * Output: ["ds-flow--md:dir-row"]
+ */
+
+import { useMemo } from "react";
+
+type BreakpointToken = "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";
+
+export type ResponsiveValue<T> = T | Partial<Record<"base" | BreakpointToken, T>>;
+
+function isResponsiveObject<T>(
+  value: ResponsiveValue<T>
+): value is Partial<Record<"base" | BreakpointToken, T>> {
+  return typeof value === "object" && value !== null;
+}
+
+/**
+ * Parse a responsive value into base value and classes.
+ */
+export function parseResponsiveValue<T extends string>(
+  component: string,
+  property: string,
+  value: ResponsiveValue<T>
+): { baseValue: T | undefined; classes: string[] } {
+  if (!isResponsiveObject(value)) {
+    return { baseValue: value, classes: [] };
+  }
+
+  const classes: string[] = [];
+  let baseValue: T | undefined;
+
+  for (const [key, val] of Object.entries(value)) {
+    if (val === undefined) continue;
+
+    if (key === "base") {
+      baseValue = val as T;
+    } else {
+      classes.push(`ds-${component}--${key}:${property}-${val}`);
+    }
+  }
+
+  return { baseValue, classes };
+}
+
+/**
+ * Hook to generate responsive CSS classes from React props.
+ */
+export function useResponsiveClasses<T extends Record<string, ResponsiveValue<string> | undefined>>(
+  component: string,
+  props: T,
+  propertyMap: Record<keyof T, string>
+): { baseValues: Partial<Record<keyof T, string>>; classes: string[] } {
+  return useMemo(() => {
+    const baseValues: Partial<Record<keyof T, string>> = {};
+    const allClasses: string[] = [];
+
+    for (const [propKey, propValue] of Object.entries(props)) {
+      if (propValue === undefined) continue;
+
+      const shortName = propertyMap[propKey as keyof T];
+      if (!shortName) continue;
+
+      const { baseValue, classes } = parseResponsiveValue(
+        component,
+        shortName,
+        propValue as ResponsiveValue<string>
+      );
+
+      if (baseValue !== undefined) {
+        baseValues[propKey as keyof T] = baseValue;
+      }
+
+      allClasses.push(...classes);
+    }
+
+    return { baseValues, classes: allClasses };
+  }, [component, props, propertyMap]);
+}
+
+/**
+ * Get the base value from a responsive value.
+ */
+export function getBaseValue<T>(value: ResponsiveValue<T>): T | undefined {
+  if (!isResponsiveObject(value)) {
+    return value;
+  }
+  return value.base;
+}

package/templates/_shared/hooks/use-stable-id.ts

@@ -0,0 +1,87 @@
+/**
+ * SSR-Safe ID Generation Hooks
+ *
+ * Provides React 18 useId()-based hooks for stable ID generation
+ * that works correctly with SSR and hydration.
+ */
+
+import { useId, useMemo } from "react";
+
+export interface UseStableIdOptions {
+  /** Custom ID to use instead of auto-generated one. */
+  id?: string;
+  /** Prefix for the generated ID. @default "ds" */
+  prefix?: string;
+}
+
+export interface UseStableIdsOptions<T extends string> extends UseStableIdOptions {
+  /** Parts to generate related IDs for. */
+  parts: readonly T[];
+}
+
+export type StableIds<T extends string> = {
+  /** The base ID */
+  baseId: string;
+} & Record<T, string>;
+
+/**
+ * Generate a stable, SSR-safe ID for a component.
+ * Uses React 18's useId() under the hood.
+ */
+export function useStableId(options: UseStableIdOptions = {}): string {
+  const { id: customId, prefix = "ds" } = options;
+
+  const reactId = useId();
+
+  const stableId = useMemo(() => {
+    if (customId) {
+      return customId;
+    }
+    const cleanId = reactId.replace(/:/g, "");
+    return `${prefix}-${cleanId}`;
+  }, [customId, prefix, reactId]);
+
+  return stableId;
+}
+
+/**
+ * Generate multiple related stable IDs for a component with multiple ARIA relationships.
+ */
+export function useStableIds<T extends string>(
+  options: UseStableIdsOptions<T>
+): StableIds<T> {
+  const { id: customId, prefix = "ds", parts } = options;
+
+  const baseId = useStableId({ id: customId, prefix });
+
+  const ids = useMemo(() => {
+    const result: Record<string, string> = { baseId };
+    for (const part of parts) {
+      result[part] = `${baseId}-${part}`;
+    }
+    return result as StableIds<T>;
+  }, [baseId, parts]);
+
+  return ids;
+}
+
+/**
+ * Create a scoped ID generator function from a base ID.
+ */
+export function useScopedIdGenerator(baseId: string): (suffix: string) => string {
+  return useMemo(() => {
+    return (suffix: string) => `${baseId}-${suffix}`;
+  }, [baseId]);
+}
+
+/**
+ * Hook to conditionally include an ID attribute.
+ */
+export function useConditionalId(id: string | undefined): string | undefined {
+  return useMemo(() => {
+    if (!id || id.trim() === "") {
+      return undefined;
+    }
+    return id;
+  }, [id]);
+}

package/templates/_shared/primitives/portal.tsx

@@ -0,0 +1,70 @@
+"use client";
+
+/**
+ * Portal React Component
+ *
+ * Renders children into a DOM node outside the parent component hierarchy.
+ * Useful for modals, tooltips, dropdowns, and other overlay patterns.
+ */
+
+import { type ReactNode, useEffect, useState } from "react";
+import { createPortal } from "react-dom";
+
+export interface PortalProps {
+  /** Content to render in the portal */
+  children: ReactNode;
+  /** Container element to render into (defaults to document.body) */
+  container?: Element | null;
+  /** CSS selector for container element (alternative to container prop) */
+  containerSelector?: string;
+  /** Whether the portal is disabled (renders children in place) */
+  disabled?: boolean;
+}
+
+/**
+ * Get the portal container element
+ */
+function getContainer(container?: Element | null, containerSelector?: string): Element | null {
+  if (typeof document === "undefined") return null;
+
+  if (container) return container;
+
+  if (containerSelector) {
+    return document.querySelector(containerSelector);
+  }
+
+  return document.body;
+}
+
+/**
+ * Portal component for rendering content outside the normal React tree.
+ */
+export function Portal({
+  children,
+  container,
+  containerSelector,
+  disabled = false,
+}: PortalProps): ReactNode {
+  const [mounted, setMounted] = useState(false);
+
+  useEffect(() => {
+    setMounted(true);
+    return () => setMounted(false);
+  }, []);
+
+  // If disabled or not mounted (SSR), render children in place
+  if (disabled || !mounted) {
+    return <>{children}</>;
+  }
+
+  const portalContainer = getContainer(container, containerSelector);
+
+  // If no container found, render in place
+  if (!portalContainer) {
+    return <>{children}</>;
+  }
+
+  return createPortal(children, portalContainer);
+}
+
+Portal.displayName = "Portal";

package/templates/_shared/primitives/responsive.ts

@@ -0,0 +1,269 @@
+/**
+ * Responsive Utilities
+ *
+ * Provides types and utilities for breakpoint-aware component props.
+ * Supports responsive object syntax for size and other props.
+ *
+ * @packageDocumentation
+ */
+
+/**
+ * Breakpoint names matching the design token system
+ */
+export type Breakpoint = "base" | "sm" | "md" | "lg" | "xl" | "2xl";
+
+/**
+ * Breakpoint values in pixels (min-width)
+ */
+export const BREAKPOINTS: Record<Breakpoint, number> = {
+  base: 0,
+  sm: 640,
+  md: 768,
+  lg: 1024,
+  xl: 1280,
+  "2xl": 1536,
+};
+
+/**
+ * Breakpoint media query strings
+ */
+export const BREAKPOINT_QUERIES: Record<Breakpoint, string> = {
+  base: "",
+  sm: "(min-width: 640px)",
+  md: "(min-width: 768px)",
+  lg: "(min-width: 1024px)",
+  xl: "(min-width: 1280px)",
+  "2xl": "(min-width: 1536px)",
+};
+
+/**
+ * Ordered list of breakpoints for cascade
+ */
+export const BREAKPOINT_ORDER: Breakpoint[] = [
+  "base",
+  "sm",
+  "md",
+  "lg",
+  "xl",
+  "2xl",
+];
+
+/**
+ * Responsive prop value type
+ *
+ * Can be either:
+ * - A single value (applies to all breakpoints)
+ * - An object with breakpoint keys (applies at each breakpoint)
+ *
+ * @example
+ * ```tsx
+ * // Single value
+ * <Button size="md" />
+ *
+ * // Responsive object
+ * <Button size={{ base: "sm", md: "md", lg: "lg" }} />
+ * ```
+ */
+export type ResponsiveProp<T> = T | Partial<Record<Breakpoint, T>>;
+
+/**
+ * Check if a value is a responsive object
+ */
+export function isResponsiveObject<T>(
+  value: ResponsiveProp<T>
+): value is Partial<Record<Breakpoint, T>> {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    !Array.isArray(value) &&
+    BREAKPOINT_ORDER.some((bp) => bp in (value as object))
+  );
+}
+
+/**
+ * Get the value for a specific breakpoint, with cascade fallback
+ */
+export function getValueAtBreakpoint<T>(
+  value: ResponsiveProp<T>,
+  breakpoint: Breakpoint
+): T | undefined {
+  if (!isResponsiveObject(value)) {
+    return value;
+  }
+
+  const targetIndex = BREAKPOINT_ORDER.indexOf(breakpoint);
+
+  for (let i = targetIndex; i >= 0; i--) {
+    const bp = BREAKPOINT_ORDER[i];
+    if (bp !== undefined && bp in value) {
+      return value[bp];
+    }
+  }
+
+  return undefined;
+}
+
+/**
+ * Get the base value from a responsive prop
+ */
+export function getBaseValue<T>(value: ResponsiveProp<T>): T | undefined {
+  return getValueAtBreakpoint(value, "base");
+}
+
+/**
+ * Resolve a responsive prop to a flat value
+ * Uses the base value or first defined value
+ */
+export function resolveResponsiveValue<T>(
+  value: ResponsiveProp<T>,
+  defaultValue: T
+): T {
+  if (!isResponsiveObject(value)) {
+    return value;
+  }
+
+  for (const bp of BREAKPOINT_ORDER) {
+    if (bp in value && value[bp] !== undefined) {
+      return value[bp] as T;
+    }
+  }
+
+  return defaultValue;
+}
+
+/**
+ * Generate CSS custom properties for responsive values
+ */
+export function generateResponsiveCssVars<T extends string>(
+  propName: string,
+  value: ResponsiveProp<T>
+): Record<string, string> {
+  const vars: Record<string, string> = {};
+
+  if (!isResponsiveObject(value)) {
+    vars[`--${propName}`] = value;
+    return vars;
+  }
+
+  for (const bp of BREAKPOINT_ORDER) {
+    if (bp in value && value[bp] !== undefined) {
+      if (bp === "base") {
+        vars[`--${propName}`] = value[bp] as string;
+      } else {
+        vars[`--${propName}-${bp}`] = value[bp] as string;
+      }
+    }
+  }
+
+  return vars;
+}
+
+/**
+ * Generate data attributes for responsive values (for CSS targeting)
+ */
+export function generateResponsiveDataAttr<T extends string>(
+  value: ResponsiveProp<T>
+): string {
+  if (!isResponsiveObject(value)) {
+    return value;
+  }
+
+  const parts: string[] = [];
+
+  for (const bp of BREAKPOINT_ORDER) {
+    if (bp in value && value[bp] !== undefined) {
+      if (bp === "base") {
+        parts.push(value[bp] as string);
+      } else {
+        parts.push(`${bp}:${value[bp]}`);
+      }
+    }
+  }
+
+  return parts.join(" ");
+}
+
+/**
+ * Hook to get current breakpoint (client-side only)
+ */
+export function useBreakpoint(): Breakpoint {
+  if (typeof window === "undefined") {
+    return "base";
+  }
+
+  const width = window.innerWidth;
+
+  if (width >= BREAKPOINTS["2xl"]) return "2xl";
+  if (width >= BREAKPOINTS.xl) return "xl";
+  if (width >= BREAKPOINTS.lg) return "lg";
+  if (width >= BREAKPOINTS.md) return "md";
+  if (width >= BREAKPOINTS.sm) return "sm";
+  return "base";
+}
+
+/**
+ * Hook to check if a breakpoint is active
+ */
+export function useBreakpointValue<T>(
+  breakpoint: Breakpoint,
+  below: T,
+  atOrAbove: T
+): T {
+  const currentBreakpoint = useBreakpoint();
+  const currentIndex = BREAKPOINT_ORDER.indexOf(currentBreakpoint);
+  const targetIndex = BREAKPOINT_ORDER.indexOf(breakpoint);
+
+  return currentIndex >= targetIndex ? atOrAbove : below;
+}
+
+/**
+ * Get responsive value for current breakpoint
+ */
+export function useResponsiveValue<T>(
+  value: ResponsiveProp<T>,
+  defaultValue: T
+): T {
+  const breakpoint = useBreakpoint();
+  const resolved = getValueAtBreakpoint(value, breakpoint);
+  return resolved ?? defaultValue;
+}
+
+/**
+ * Type helper for component props that support responsive values
+ */
+export type WithResponsive<T, K extends keyof T> = Omit<T, K> & {
+  [P in K]?: ResponsiveProp<NonNullable<T[P]>>;
+};
+
+/**
+ * CSS generation utilities for responsive styles
+ */
+export const responsiveCss = {
+  /**
+   * Generate media query CSS for responsive prop
+   */
+  generateMediaQueries<T extends string>(
+    _propName: string,
+    value: ResponsiveProp<T>,
+    cssGenerator: (val: T) => string
+  ): string {
+    if (!isResponsiveObject(value)) {
+      return cssGenerator(value);
+    }
+
+    const rules: string[] = [];
+
+    for (const bp of BREAKPOINT_ORDER) {
+      if (bp in value && value[bp] !== undefined) {
+        const css = cssGenerator(value[bp] as T);
+        if (bp === "base") {
+          rules.push(css);
+        } else {
+          rules.push(`@media ${BREAKPOINT_QUERIES[bp]} { ${css} }`);
+        }
+      }
+    }
+
+    return rules.join("\n");
+  },
+};

package/templates/_shared/primitives/slot.tsx

@@ -0,0 +1,103 @@
+import {
+  Children,
+  type HTMLAttributes,
+  type ReactNode,
+  type Ref,
+  cloneElement,
+  forwardRef,
+  isValidElement,
+  useEffect,
+  useRef,
+} from "react";
+import { mergeProps } from "../utils/merge-props.js";
+
+export interface SlotProps extends HTMLAttributes<HTMLElement> {
+  children?: ReactNode;
+}
+
+/**
+ * Merges two refs into a single ref callback.
+ */
+function mergeRefs<T>(...refs: (Ref<T> | undefined)[]): (instance: T | null) => void {
+  return (instance: T | null) => {
+    for (const ref of refs) {
+      if (typeof ref === "function") {
+        ref(instance);
+      } else if (ref && typeof ref === "object") {
+        (ref as { current: T | null }).current = instance;
+      }
+    }
+  };
+}
+
+/**
+ * Slot renders its child element with merged props.
+ * Used internally by asChild implementations.
+ *
+ * - Validates that children is a single React element
+ * - Merges props (className concatenated, styles merged, events composed)
+ * - Forwards refs to the child element
+ */
+export const Slot = forwardRef<HTMLElement, SlotProps>(
+  ({ children, ...slotProps }, forwardedRef) => {
+    const childrenArray = Children.toArray(children);
+    const internalRef = useRef<HTMLElement | null>(null);
+
+    // Filter out null/undefined/boolean children
+    const validChildren = childrenArray.filter(
+      (child) => child !== null && child !== undefined && typeof child !== "boolean"
+    );
+
+    if (validChildren.length === 0) {
+      throw new Error("Slot expects a single React element child");
+    }
+
+    if (validChildren.length > 1) {
+      throw new Error("Slot expects a single React element child, received multiple children");
+    }
+
+    const child = validChildren[0];
+
+    if (!isValidElement(child)) {
+      throw new Error(`Slot expects a single React element child, received ${typeof child}`);
+    }
+
+    // Check if child is a custom component (not an intrinsic element)
+    const isCustomComponent = typeof child.type === "function" || typeof child.type === "object";
+
+    // Warn in development if the child component doesn't forward refs
+    useEffect(() => {
+      if (
+        process.env.NODE_ENV !== "production" &&
+        isCustomComponent &&
+        internalRef.current === null
+      ) {
+        const componentName =
+          typeof child.type === "function"
+            ? (child.type as { displayName?: string; name?: string }).displayName ||
+              (child.type as { name?: string }).name ||
+              "Component"
+            : "Component";
+        console.warn(
+          `[Slot] The child component "${componentName}" doesn't forward refs. When using asChild, ensure the child component is wrapped with React.forwardRef() and forwards the ref to its underlying DOM element. This is required for proper focus management and accessibility.`
+        );
+      }
+    }, [isCustomComponent, child.type]);
+
+    // Get child's ref if it exists
+    const childRef = (child as { ref?: Ref<HTMLElement> }).ref;
+
+    // Merge props and refs
+    const mergedProps = mergeProps(
+      slotProps as Record<string, unknown>,
+      child.props as Record<string, unknown>
+    );
+
+    return cloneElement(child, {
+      ...mergedProps,
+      ref: mergeRefs(forwardedRef, childRef, internalRef),
+    } as Record<string, unknown>);
+  }
+);
+
+Slot.displayName = "Slot";

package/templates/_shared/types/events.ts

@@ -0,0 +1,21 @@
+/**
+ * Event type definitions for React wrapper components.
+ * These types match the custom events emitted by Web Components.
+ */
+
+export interface DsNavigateEventDetail {
+  /** The target URL */
+  href: string;
+  /** Whether the link opens in a new tab */
+  external: boolean;
+  /** The original DOM event that triggered navigation */
+  originalEvent: MouseEvent | KeyboardEvent;
+}
+
+export interface DsInputEventDetail {
+  value: string;
+}
+
+export type NavigateEventHandler = (event: CustomEvent<DsNavigateEventDetail>) => void;
+
+export type InputValueHandler = (value: string, event: CustomEvent<DsInputEventDetail>) => void;

package/templates/_shared/types/polymorphic.ts

@@ -0,0 +1,32 @@
+/**
+ * Polymorphic type utilities for asChild pattern.
+ */
+
+export type SpacingValue = 0 | 1 | 2 | 3 | 4 | 5 | 6 | 8 | 10 | 12 | 16 | 20 | 24;
+
+export type DisplayValue =
+  | "block"
+  | "inline"
+  | "inline-block"
+  | "flex"
+  | "inline-flex"
+  | "grid"
+  | "inline-grid"
+  | "none";
+
+export type FlexDirection = "row" | "row-reverse" | "column" | "column-reverse";
+
+export type AlignValue = "start" | "end" | "center" | "stretch" | "baseline";
+
+export type JustifyValue = "start" | "end" | "center" | "between" | "around" | "evenly";
+
+/**
+ * Base props for components supporting asChild pattern.
+ */
+export interface AsChildProps {
+  /**
+   * When true, the component renders its child element with merged props
+   * instead of its default element.
+   */
+  asChild?: boolean;
+}

package/templates/_shared/utils/create-context.ts

@@ -0,0 +1,22 @@
+import { type Provider, createContext, useContext } from "react";
+
+/**
+ * Creates a compound component context with a built-in hook.
+ * Throws a helpful error when used outside the provider.
+ */
+export function createCompoundContext<T>(
+  displayName: string
+): [Provider<T>, (consumerName: string) => T] {
+  const Context = createContext<T | null>(null);
+  Context.displayName = displayName;
+
+  function useCompoundContext(consumerName: string): T {
+    const context = useContext(Context);
+    if (context === null) {
+      throw new Error(`<${consumerName}> must be used within <${displayName}.Root>`);
+    }
+    return context;
+  }
+
+  return [Context.Provider as Provider<T>, useCompoundContext];
+}

package/templates/_shared/utils/merge-props.ts

@@ -0,0 +1,88 @@
+import type { CSSProperties, SyntheticEvent } from "react";
+
+/**
+ * Composes two event handlers, calling child handler first.
+ * If child handler calls preventDefault(), parent handler is skipped.
+ */
+export function composeEventHandlers<E extends SyntheticEvent | Event>(
+  parentHandler?: (event: E) => void,
+  childHandler?: (event: E) => void
+): (event: E) => void {
+  return (event: E) => {
+    childHandler?.(event);
+    if (
+      !("defaultPrevented" in event) ||
+      !(event as { defaultPrevented: boolean }).defaultPrevented
+    ) {
+      parentHandler?.(event);
+    }
+  };
+}
+
+/**
+ * Merges two className strings, filtering out falsy values.
+ */
+export function mergeClassNames(...classNames: (string | undefined | null | false)[]): string {
+  return classNames.filter(Boolean).join(" ");
+}
+
+/**
+ * Merges two style objects, with child styles taking precedence.
+ */
+export function mergeStyles(
+  parentStyle?: CSSProperties,
+  childStyle?: CSSProperties
+): CSSProperties | undefined {
+  if (!parentStyle && !childStyle) return undefined;
+  if (!parentStyle) return childStyle;
+  if (!childStyle) return parentStyle;
+  return { ...parentStyle, ...childStyle };
+}
+
+/**
+ * Checks if a prop name is an event handler (starts with 'on' followed by uppercase).
+ */
+function isEventHandler(propName: string): boolean {
+  return /^on[A-Z]/.test(propName);
+}
+
+/**
+ * Merges slot props with child props.
+ * - className: concatenated
+ * - style: merged (child wins conflicts)
+ * - event handlers: composed (both called, child first)
+ * - other props: child wins
+ */
+export function mergeProps<T extends Record<string, unknown>>(slotProps: T, childProps: T): T {
+  const result = { ...slotProps } as T;
+
+  for (const key in childProps) {
+    const slotValue = slotProps[key];
+    const childValue = childProps[key];
+
+    if (key === "className") {
+      result[key] = mergeClassNames(
+        slotValue as string | undefined,
+        childValue as string | undefined
+      ) as T[typeof key];
+    } else if (key === "style") {
+      result[key] = mergeStyles(
+        slotValue as CSSProperties | undefined,
+        childValue as CSSProperties | undefined
+      ) as T[typeof key];
+    } else if (
+      isEventHandler(key) &&
+      typeof slotValue === "function" &&
+      typeof childValue === "function"
+    ) {
+      result[key] = composeEventHandlers(
+        slotValue as (event: Event) => void,
+        childValue as (event: Event) => void
+      ) as T[typeof key];
+    } else if (childValue !== undefined) {
+      result[key] = childValue;
+    }
+  }
+
+  return result;
+}

package/templates/avatar/avatar-group.tsx

@@ -7,7 +7,7 @@ import {
   generateResponsiveDataAttr,
   isResponsiveObject,
   resolveResponsiveValue,
-} from "../../primitives/responsive.js";
+} from "../_shared/primitives/responsive.js";
 import type { AvatarSize } from "./avatar.js";
 
 export interface AvatarGroupProps extends HTMLAttributes<HTMLElement> {

package/templates/avatar/avatar.tsx

@@ -7,7 +7,7 @@ import {
   generateResponsiveDataAttr,
   isResponsiveObject,
   resolveResponsiveValue,
-} from "../../primitives/responsive.js";
+} from "../_shared/primitives/responsive.js";
 
 export type AvatarSize = "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
 export type AvatarShape = "circle" | "square";

package/templates/badge/index.tsx

@@ -7,7 +7,7 @@ import {
   generateResponsiveDataAttr,
   isResponsiveObject,
   resolveResponsiveValue,
-} from "../../primitives/responsive.js";
+} from "../_shared/primitives/responsive.js";
 
 export type BadgeVariant =
   | "neutral"

package/templates/button/button.tsx

@@ -12,7 +12,7 @@ import {
   useEffect,
   useMemo,
 } from "react";
-import { Slot } from "../../primitives/slot.js";
+import { Slot } from "../_shared/primitives/slot.js";
 
 export interface ButtonProps
   extends Omit<ButtonHTMLAttributes<HTMLButtonElement>, "type" | "disabled"> {

package/templates/combobox/combobox-context.ts

@@ -3,7 +3,7 @@
  */
 
 import type { ComboboxBehavior, Option } from "@hypoth-ui/primitives-dom";
-import { createCompoundContext } from "../../utils/create-context.js";
+import { createCompoundContext } from "../_shared/utils/create-context.js";
 
 export interface ComboboxContextValue<Multi extends boolean = false> {
   /** Combobox behavior instance */

package/templates/date-picker/date-picker-context.ts

@@ -3,7 +3,7 @@
  */
 
 import type { DatePickerBehavior, DateRange } from "@hypoth-ui/primitives-dom";
-import { createCompoundContext } from "../../utils/create-context.js";
+import { createCompoundContext } from "../_shared/utils/create-context.js";
 
 export type DatePickerMode = "single" | "range";
 

package/templates/date-picker/date-picker-trigger.tsx

@@ -3,7 +3,7 @@
  */
 
 import { type ButtonHTMLAttributes, type ReactNode, forwardRef, useCallback, useRef } from "react";
-import { Slot } from "../../primitives/slot.js";
+import { Slot } from "../_shared/primitives/slot.js";
 import { useDatePickerContext } from "./date-picker-context.js";
 
 export interface DatePickerTriggerProps extends ButtonHTMLAttributes<HTMLButtonElement> {

package/templates/dialog/dialog-close.tsx

@@ -3,7 +3,7 @@
  */
 
 import { type ButtonHTMLAttributes, type ReactNode, forwardRef, useCallback } from "react";
-import { Slot } from "../../primitives/slot.js";
+import { Slot } from "../_shared/primitives/slot.js";
 import { useDialogContext } from "./dialog-context.js";
 
 export interface DialogCloseProps extends ButtonHTMLAttributes<HTMLButtonElement> {

package/templates/dialog/dialog-context.ts

@@ -3,7 +3,7 @@
  */
 
 import type { DialogBehavior } from "@hypoth-ui/primitives-dom";
-import { createCompoundContext } from "../../utils/create-context.js";
+import { createCompoundContext } from "../_shared/utils/create-context.js";
 
 export interface DialogContextValue {
   /** Dialog behavior instance */

package/templates/dialog/dialog-root.tsx

@@ -4,7 +4,7 @@
 
 import { type DialogRole, createDialogBehavior } from "@hypoth-ui/primitives-dom";
 import { type ReactNode, useCallback, useMemo, useState } from "react";
-import { useStableId } from "../../hooks/use-stable-id.js";
+import { useStableId } from "../_shared/hooks/use-stable-id.js";
 import { DialogProvider } from "./dialog-context.js";
 
 export interface DialogRootProps {

package/templates/dialog/dialog-trigger.tsx

@@ -10,7 +10,7 @@ import {
   useEffect,
   useRef,
 } from "react";
-import { Slot } from "../../primitives/slot.js";
+import { Slot } from "../_shared/primitives/slot.js";
 import { useDialogContext } from "./dialog-context.js";
 
 export interface DialogTriggerProps extends ButtonHTMLAttributes<HTMLButtonElement> {

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

@@ -3,7 +3,7 @@
  */
 
 import type { FileInfo, FileUploadBehavior } from "@hypoth-ui/primitives-dom";
-import { createCompoundContext } from "../../utils/create-context.js";
+import { createCompoundContext } from "../_shared/utils/create-context.js";
 
 export interface FileUploadContextValue {
   /** FileUpload behavior instance */

package/templates/icon/icon.tsx

@@ -4,7 +4,7 @@ import {
   generateResponsiveDataAttr,
   isResponsiveObject,
   resolveResponsiveValue,
-} from "../primitives/responsive.js";
+} from "../_shared/primitives/responsive.js";
 
 export type IconSize = "xs" | "sm" | "md" | "lg" | "xl";
 

package/templates/layout/flow.tsx

@@ -6,7 +6,7 @@
 
 import type React from "react";
 import { createElement, forwardRef, useMemo } from "react";
-import { type ResponsiveValue, parseResponsiveValue } from "../../hooks/use-responsive-classes.js";
+import { type ResponsiveValue, parseResponsiveValue } from "../_shared/hooks/use-responsive-classes.js";
 
 type FlexDirection = "row" | "column" | "row-reverse" | "column-reverse";
 type FlexAlign = "start" | "center" | "end" | "stretch" | "baseline";

package/templates/layout/grid.tsx

@@ -6,7 +6,7 @@
 
 import type React from "react";
 import { createElement, forwardRef, useMemo } from "react";
-import { type ResponsiveValue, parseResponsiveValue } from "../../hooks/use-responsive-classes.js";
+import { type ResponsiveValue, parseResponsiveValue } from "../_shared/hooks/use-responsive-classes.js";
 
 type GridColumns = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12 | "auto-fit" | "auto-fill";
 type SpacingToken = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";

package/templates/link/link.tsx

@@ -1,9 +1,9 @@
 import type { AnchorHTMLAttributes, ReactNode } from "react";
 import { createElement, forwardRef, useCallback, useEffect, useRef } from "react";
-import { Slot } from "../primitives/slot.js";
-import type { DsNavigateEventDetail, NavigateEventHandler } from "../types/events.js";
-import type { AsChildProps } from "../types/polymorphic.js";
-import { mergeClassNames } from "../utils/merge-props.js";
+import { Slot } from "../_shared/primitives/slot.js";
+import type { DsNavigateEventDetail, NavigateEventHandler } from "../_shared/types/events.js";
+import type { AsChildProps } from "../_shared/types/polymorphic.js";
+import { mergeClassNames } from "../_shared/utils/merge-props.js";
 
 export type LinkVariant = "default" | "muted" | "underline";
 

package/templates/menu/menu-context.ts

@@ -3,7 +3,7 @@
  */
 
 import type { MenuBehavior } from "@hypoth-ui/primitives-dom";
-import { createCompoundContext } from "../../utils/create-context.js";
+import { createCompoundContext } from "../_shared/utils/create-context.js";
 
 export interface MenuContextValue {
   /** Menu behavior instance */

package/templates/menu/menu-root.tsx

@@ -4,7 +4,7 @@
 
 import { type Placement, createMenuBehavior } from "@hypoth-ui/primitives-dom";
 import { type ReactNode, useCallback, useMemo, useState } from "react";
-import { useStableId } from "../../hooks/use-stable-id.js";
+import { useStableId } from "../_shared/hooks/use-stable-id.js";
 import { MenuProvider } from "./menu-context.js";
 
 export interface MenuRootProps {

package/templates/menu/menu-trigger.tsx

@@ -10,7 +10,7 @@ import {
   useEffect,
   useRef,
 } from "react";
-import { Slot } from "../../primitives/slot.js";
+import { Slot } from "../_shared/primitives/slot.js";
 import { useMenuContext } from "./menu-context.js";
 
 export interface MenuTriggerProps extends ButtonHTMLAttributes<HTMLButtonElement> {

package/templates/number-input/number-input-context.ts

@@ -3,7 +3,7 @@
  */
 
 import type { NumberInputBehavior } from "@hypoth-ui/primitives-dom";
-import { createCompoundContext } from "../../utils/create-context.js";
+import { createCompoundContext } from "../_shared/utils/create-context.js";
 
 export type NumberInputFormat = "decimal" | "currency" | "percent";
 

package/templates/pin-input/pin-input-context.ts

@@ -3,7 +3,7 @@
  */
 
 import type { PinInputBehavior } from "@hypoth-ui/primitives-dom";
-import { createCompoundContext } from "../../utils/create-context.js";
+import { createCompoundContext } from "../_shared/utils/create-context.js";
 
 export interface PinInputContextValue {
   /** PinInput behavior instance */

package/templates/progress/index.tsx

@@ -7,7 +7,7 @@ import {
   generateResponsiveDataAttr,
   isResponsiveObject,
   resolveResponsiveValue,
-} from "../../primitives/responsive.js";
+} from "../_shared/primitives/responsive.js";
 
 export type ProgressVariant = "linear" | "circular";
 export type ProgressSize = "sm" | "md" | "lg";

package/templates/select/select-context.ts

@@ -3,7 +3,7 @@
  */
 
 import type { SelectBehavior } from "@hypoth-ui/primitives-dom";
-import { createCompoundContext } from "../../utils/create-context.js";
+import { createCompoundContext } from "../_shared/utils/create-context.js";
 
 export interface SelectContextValue {
   /** Select behavior instance */

package/templates/select/select-root.tsx

@@ -4,7 +4,7 @@
 
 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 { useStableId } from "../_shared/hooks/use-stable-id.js";
 import { SelectProvider } from "./select-context.js";
 
 export interface SelectRootProps {

package/templates/select/select-trigger.tsx

@@ -3,7 +3,7 @@
  */
 
 import { type ButtonHTMLAttributes, type ReactNode, forwardRef, useCallback, useRef } from "react";
-import { Slot } from "../../primitives/slot.js";
+import { Slot } from "../_shared/primitives/slot.js";
 import { useSelectContext } from "./select-context.js";
 
 export interface SelectTriggerProps extends ButtonHTMLAttributes<HTMLButtonElement> {

package/templates/skeleton/index.tsx

@@ -7,7 +7,7 @@ import {
   generateResponsiveDataAttr,
   isResponsiveObject,
   resolveResponsiveValue,
-} from "../../primitives/responsive.js";
+} from "../_shared/primitives/responsive.js";
 
 export type SkeletonVariant = "text" | "circular" | "rectangular" | "rounded";
 export type SkeletonSize = "xs" | "sm" | "md" | "lg" | "xl";

package/templates/slider/slider-context.ts

@@ -3,7 +3,7 @@
  */
 
 import type { SliderBehavior } from "@hypoth-ui/primitives-dom";
-import { createCompoundContext } from "../../utils/create-context.js";
+import { createCompoundContext } from "../_shared/utils/create-context.js";
 
 export interface SliderContextValue {
   /** Slider behavior instance */

package/templates/spinner/spinner.tsx

@@ -4,7 +4,7 @@ import {
   generateResponsiveDataAttr,
   isResponsiveObject,
   resolveResponsiveValue,
-} from "../primitives/responsive.js";
+} from "../_shared/primitives/responsive.js";
 
 export type SpinnerSize = "sm" | "md" | "lg";
 

package/templates/tag/index.tsx

@@ -14,7 +14,7 @@ import {
   generateResponsiveDataAttr,
   isResponsiveObject,
   resolveResponsiveValue,
-} from "../../primitives/responsive.js";
+} from "../_shared/primitives/responsive.js";
 
 export type TagVariant =
   | "neutral"

package/templates/text/text.tsx

@@ -1,8 +1,8 @@
 import type { ReactNode } from "react";
 import { createElement, forwardRef } from "react";
-import { Slot } from "../primitives/slot.js";
-import type { AsChildProps } from "../types/polymorphic.js";
-import { mergeClassNames } from "../utils/merge-props.js";
+import { Slot } from "../_shared/primitives/slot.js";
+import type { AsChildProps } from "../_shared/types/polymorphic.js";
+import { mergeClassNames } from "../_shared/utils/merge-props.js";
 
 export type TextSize = "xs" | "sm" | "md" | "lg" | "xl" | "2xl";
 export type TextWeight = "normal" | "medium" | "semibold" | "bold";

package/templates/textarea/textarea.tsx

@@ -12,7 +12,7 @@ import {
   generateResponsiveDataAttr,
   isResponsiveObject,
   resolveResponsiveValue,
-} from "../primitives/responsive.js";
+} from "../_shared/primitives/responsive.js";
 
 export type TextareaSize = "sm" | "md" | "lg";
 

package/templates/time-picker/time-picker-context.ts

@@ -3,7 +3,7 @@
  */
 
 import type { TimePickerBehavior, TimeSegment, TimeValue } from "@hypoth-ui/primitives-dom";
-import { createCompoundContext } from "../../utils/create-context.js";
+import { createCompoundContext } from "../_shared/utils/create-context.js";
 
 export interface TimePickerContextValue {
   /** TimePicker behavior instance */

package/templates/toast/provider.tsx

@@ -7,7 +7,7 @@
  */
 
 import { type ReactNode, createContext, useCallback, useMemo, useState } from "react";
-import { Portal } from "../../primitives/portal.js";
+import { Portal } from "../_shared/primitives/portal.js";
 import { ToastItem } from "./toast.js";
 
 export type ToastVariant = "info" | "success" | "warning" | "error";