@hypoth-ui/cli 0.0.1 → 0.1.0

package/templates/layout/app-shell.tsx

@@ -0,0 +1,177 @@
+/**
+ * AppShell React Component
+ *
+ * Application structure with compound component pattern.
+ */
+
+import type React from "react";
+import { createElement, forwardRef } from "react";
+
+type SidebarPosition = "left" | "right" | "none";
+
+// ============================================
+// AppShell Root
+// ============================================
+
+export interface AppShellProps {
+  /** Sidebar position. */
+  sidebarPosition?: SidebarPosition;
+  /** Additional CSS class names. */
+  className?: string;
+  /** Children elements. */
+  children?: React.ReactNode;
+}
+
+const AppShellRoot = forwardRef<HTMLElement, AppShellProps>((props, ref) => {
+  const { sidebarPosition = "none", className, children, ...rest } = props;
+
+  return createElement(
+    "ds-app-shell",
+    {
+      ref,
+      "sidebar-position": sidebarPosition,
+      class: className,
+      ...rest,
+    },
+    children
+  );
+});
+
+AppShellRoot.displayName = "AppShell";
+
+// ============================================
+// Header Sub-component
+// ============================================
+
+export interface HeaderProps {
+  /** Enable sticky positioning. */
+  sticky?: boolean;
+  /** Enable safe area insets. */
+  safeArea?: boolean;
+  /** Additional CSS class names. */
+  className?: string;
+  /** Children elements. */
+  children?: React.ReactNode;
+}
+
+const Header = forwardRef<HTMLElement, HeaderProps>((props, ref) => {
+  const { sticky = false, safeArea = false, className, children, ...rest } = props;
+
+  return createElement(
+    "ds-header",
+    {
+      ref,
+      slot: "header",
+      sticky: sticky || undefined,
+      "safe-area": safeArea || undefined,
+      class: className,
+      ...rest,
+    },
+    children
+  );
+});
+
+Header.displayName = "AppShell.Header";
+
+// ============================================
+// Footer Sub-component
+// ============================================
+
+export interface FooterProps {
+  /** Enable sticky positioning. */
+  sticky?: boolean;
+  /** Enable safe area insets. */
+  safeArea?: boolean;
+  /** Additional CSS class names. */
+  className?: string;
+  /** Children elements. */
+  children?: React.ReactNode;
+}
+
+const Footer = forwardRef<HTMLElement, FooterProps>((props, ref) => {
+  const { sticky = false, safeArea = false, className, children, ...rest } = props;
+
+  return createElement(
+    "ds-footer",
+    {
+      ref,
+      slot: "footer",
+      sticky: sticky || undefined,
+      "safe-area": safeArea || undefined,
+      class: className,
+      ...rest,
+    },
+    children
+  );
+});
+
+Footer.displayName = "AppShell.Footer";
+
+// ============================================
+// Main Sub-component
+// ============================================
+
+export interface MainProps {
+  /** Element ID for skip-link targeting. */
+  id?: string;
+  /** Additional CSS class names. */
+  className?: string;
+  /** Children elements. */
+  children?: React.ReactNode;
+}
+
+const Main = forwardRef<HTMLElement, MainProps>((props, ref) => {
+  const { id = "main-content", className, children, ...rest } = props;
+
+  return createElement(
+    "ds-main",
+    {
+      ref,
+      id,
+      class: className,
+      ...rest,
+    },
+    children
+  );
+});
+
+Main.displayName = "AppShell.Main";
+
+// ============================================
+// Sidebar Sub-component
+// ============================================
+
+export interface SidebarProps {
+  /** Additional CSS class names. */
+  className?: string;
+  /** Children elements. */
+  children?: React.ReactNode;
+}
+
+const Sidebar = forwardRef<HTMLElement, SidebarProps>((props, ref) => {
+  const { className, children, ...rest } = props;
+
+  return createElement(
+    "aside",
+    {
+      ref,
+      slot: "sidebar",
+      class: `ds-sidebar ${className || ""}`.trim(),
+      ...rest,
+    },
+    children
+  );
+});
+
+Sidebar.displayName = "AppShell.Sidebar";
+
+// ============================================
+// Compound Component Export
+// ============================================
+
+export const AppShell = Object.assign(AppShellRoot, {
+  Header,
+  Footer,
+  Main,
+  Sidebar,
+});

package/templates/layout/box.tsx

@@ -0,0 +1,53 @@
+/**
+ * Box React Component
+ *
+ * Token-only styling escape hatch for padding, background, and radius.
+ */
+
+import type React from "react";
+import { createElement, forwardRef } from "react";
+
+type SpacingToken = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";
+type SurfaceToken = "background" | "surface" | "surface-raised" | "surface-sunken" | "muted";
+type RadiusToken = "none" | "sm" | "md" | "lg" | "xl" | "full";
+
+export interface BoxProps {
+  /** Padding (all sides). */
+  p?: SpacingToken;
+  /** Horizontal padding. */
+  px?: SpacingToken;
+  /** Vertical padding. */
+  py?: SpacingToken;
+  /** Background color token. */
+  bg?: SurfaceToken;
+  /** Border radius token. */
+  radius?: RadiusToken;
+  /** Additional CSS class names. */
+  className?: string;
+  /** Children elements. */
+  children?: React.ReactNode;
+}
+
+/**
+ * React wrapper for ds-box Web Component.
+ */
+export const Box = forwardRef<HTMLElement, BoxProps>((props, ref) => {
+  const { p, px, py, bg, radius, className, children, ...rest } = props;
+
+  return createElement(
+    "ds-box",
+    {
+      ref,
+      p,
+      px,
+      py,
+      bg,
+      radius,
+      class: className,
+      ...rest,
+    },
+    children
+  );
+});
+
+Box.displayName = "Box";

package/templates/layout/center.tsx

@@ -0,0 +1,42 @@
+/**
+ * Center React Component
+ *
+ * Centers content horizontally/vertically with optional max-width.
+ */
+
+import type React from "react";
+import { createElement, forwardRef } from "react";
+
+type ContainerSizeToken = "sm" | "md" | "lg" | "xl" | "2xl" | "full";
+
+export interface CenterProps {
+  /** Maximum width constraint. */
+  maxWidth?: ContainerSizeToken;
+  /** Enable vertical centering. */
+  vertical?: boolean;
+  /** Additional CSS class names. */
+  className?: string;
+  /** Children elements. */
+  children?: React.ReactNode;
+}
+
+/**
+ * React wrapper for ds-center Web Component.
+ */
+export const Center = forwardRef<HTMLElement, CenterProps>((props, ref) => {
+  const { maxWidth, vertical = false, className, children, ...rest } = props;
+
+  return createElement(
+    "ds-center",
+    {
+      ref,
+      "max-width": maxWidth,
+      vertical: vertical || undefined,
+      class: className,
+      ...rest,
+    },
+    children
+  );
+});
+
+Center.displayName = "Center";

package/templates/layout/container.tsx

@@ -0,0 +1,43 @@
+/**
+ * Container React Component
+ *
+ * Constrains content width with responsive max-widths and padding.
+ */
+
+import type React from "react";
+import { createElement, forwardRef } from "react";
+
+type ContainerSizeToken = "sm" | "md" | "lg" | "xl" | "2xl" | "full";
+type SpacingToken = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";
+
+export interface ContainerProps {
+  /** Maximum width constraint. */
+  size?: ContainerSizeToken;
+  /** Horizontal padding. */
+  padding?: SpacingToken;
+  /** Additional CSS class names. */
+  className?: string;
+  /** Children elements. */
+  children?: React.ReactNode;
+}
+
+/**
+ * React wrapper for ds-container Web Component.
+ */
+export const Container = forwardRef<HTMLElement, ContainerProps>((props, ref) => {
+  const { size = "lg", padding = "md", className, children, ...rest } = props;
+
+  return createElement(
+    "ds-container",
+    {
+      ref,
+      size,
+      padding,
+      class: className,
+      ...rest,
+    },
+    children
+  );
+});
+
+Container.displayName = "Container";

package/templates/layout/flow.tsx

@@ -0,0 +1,83 @@
+/**
+ * Flow React Component
+ *
+ * Primary 1D layout primitive with responsive direction switching.
+ */
+
+import type React from "react";
+import { createElement, forwardRef, useMemo } from "react";
+import { type ResponsiveValue, parseResponsiveValue } from "../../hooks/use-responsive-classes.js";
+
+type FlexDirection = "row" | "column" | "row-reverse" | "column-reverse";
+type FlexAlign = "start" | "center" | "end" | "stretch" | "baseline";
+type FlexJustify = "start" | "center" | "end" | "between" | "around" | "evenly";
+type FlexWrap = "nowrap" | "wrap" | "wrap-reverse";
+type SpacingToken = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";
+
+export interface FlowProps {
+  /** Flex direction. Supports responsive object syntax. */
+  direction?: ResponsiveValue<FlexDirection>;
+  /** Gap between children. Supports responsive object syntax. */
+  gap?: ResponsiveValue<SpacingToken>;
+  /** Cross-axis alignment. */
+  align?: FlexAlign;
+  /** Main-axis alignment. */
+  justify?: FlexJustify;
+  /** Flex wrap behavior. */
+  wrap?: FlexWrap;
+  /** Use inline-flex instead of flex. */
+  inline?: boolean;
+  /** Additional CSS class names. */
+  className?: string;
+  /** Children elements. */
+  children?: React.ReactNode;
+}
+
+/**
+ * React wrapper for ds-flow Web Component.
+ */
+export const Flow = forwardRef<HTMLElement, FlowProps>((props, ref) => {
+  const {
+    direction = "row",
+    gap = "none",
+    align = "stretch",
+    justify = "start",
+    wrap = "nowrap",
+    inline = false,
+    className,
+    children,
+    ...rest
+  } = props;
+
+  // Parse responsive values
+  const directionResult = useMemo(
+    () => parseResponsiveValue("flow", "dir", direction),
+    [direction]
+  );
+  const gapResult = useMemo(() => parseResponsiveValue("flow", "gap", gap), [gap]);
+
+  // Combine all classes
+  const allClasses = useMemo(() => {
+    const classes = [...directionResult.classes, ...gapResult.classes];
+    if (className) classes.push(className);
+    return classes.join(" ") || undefined;
+  }, [directionResult.classes, gapResult.classes, className]);
+
+  return createElement(
+    "ds-flow",
+    {
+      ref,
+      direction: directionResult.baseValue,
+      gap: gapResult.baseValue,
+      align,
+      justify,
+      wrap,
+      inline: inline || undefined,
+      class: allClasses,
+      ...rest,
+    },
+    children
+  );
+});
+
+Flow.displayName = "Flow";

package/templates/layout/grid.tsx

@@ -0,0 +1,79 @@
+/**
+ * Grid React Component
+ *
+ * 2D grid layout with responsive columns.
+ */
+
+import type React from "react";
+import { createElement, forwardRef, useMemo } from "react";
+import { type ResponsiveValue, parseResponsiveValue } from "../../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";
+
+export interface GridProps {
+  /** Number of columns. Supports responsive object syntax. */
+  columns?: ResponsiveValue<GridColumns>;
+  /** Gap between grid items. Supports responsive object syntax. */
+  gap?: ResponsiveValue<SpacingToken>;
+  /** Row gap override. */
+  rowGap?: SpacingToken;
+  /** Column gap override. */
+  columnGap?: SpacingToken;
+  /** Additional CSS class names. */
+  className?: string;
+  /** Children elements. */
+  children?: React.ReactNode;
+}
+
+/**
+ * React wrapper for ds-grid Web Component.
+ */
+export const Grid = forwardRef<HTMLElement, GridProps>((props, ref) => {
+  const { columns = 1, gap = "md", rowGap, columnGap, className, children, ...rest } = props;
+
+  // Parse responsive values - convert numbers to strings
+  const columnsValue = useMemo(() => {
+    if (typeof columns === "number") {
+      return String(columns);
+    }
+    if (typeof columns === "object") {
+      const converted: Record<string, string> = {};
+      for (const [key, val] of Object.entries(columns)) {
+        converted[key] = String(val);
+      }
+      return converted;
+    }
+    return columns;
+  }, [columns]);
+
+  const columnsResult = useMemo(
+    () => parseResponsiveValue("grid", "cols", columnsValue as ResponsiveValue<string>),
+    [columnsValue]
+  );
+
+  const gapResult = useMemo(() => parseResponsiveValue("grid", "gap", gap), [gap]);
+
+  // Combine all classes
+  const allClasses = useMemo(() => {
+    const classes = [...columnsResult.classes, ...gapResult.classes];
+    if (className) classes.push(className);
+    return classes.join(" ") || undefined;
+  }, [columnsResult.classes, gapResult.classes, className]);
+
+  return createElement(
+    "ds-grid",
+    {
+      ref,
+      columns: columnsResult.baseValue,
+      gap: gapResult.baseValue,
+      "row-gap": rowGap,
+      "column-gap": columnGap,
+      class: allClasses,
+      ...rest,
+    },
+    children
+  );
+});
+
+Grid.displayName = "Grid";

package/templates/layout/index.ts

@@ -0,0 +1,33 @@
+/**
+ * Layout Components Index
+ *
+ * Exports all layout primitive React components.
+ */
+
+// Core Layout
+export { Flow, type FlowProps } from "./flow.js";
+export { Container, type ContainerProps } from "./container.js";
+export { Grid, type GridProps } from "./grid.js";
+export { Box, type BoxProps } from "./box.js";
+
+// Page Composition
+export { Page, type PageProps } from "./page.js";
+export { Section, type SectionProps } from "./section.js";
+export {
+  AppShell,
+  type AppShellProps,
+  type HeaderProps,
+  type FooterProps,
+  type MainProps,
+  type SidebarProps,
+} from "./app-shell.js";
+
+// Helpers
+export { Spacer, type SpacerProps } from "./spacer.js";
+export { Center, type CenterProps } from "./center.js";
+export { Split, type SplitProps } from "./split.js";
+export { Wrap, type WrapProps } from "./wrap.js";
+
+// Aliases
+export { Stack, type StackProps } from "./stack.js";
+export { Inline, type InlineProps } from "./inline.js";

package/templates/layout/inline.tsx

@@ -0,0 +1,16 @@
+import { forwardRef } from "react";
+import { Flow, type FlowProps } from "./flow.js";
+
+export interface InlineProps extends Omit<FlowProps, "direction"> {
+  /** Gap between children. Supports responsive object syntax. */
+  gap?: FlowProps["gap"];
+}
+
+/**
+ * Inline is a Flow with direction="row".
+ */
+export const Inline = forwardRef<HTMLElement, InlineProps>((props, ref) => {
+  return <Flow ref={ref} direction="row" {...props} />;
+});
+
+Inline.displayName = "Inline";

package/templates/layout/page.tsx

@@ -0,0 +1,43 @@
+/**
+ * Page React Component
+ *
+ * Page wrapper with min-height and background.
+ */
+
+import type React from "react";
+import { createElement, forwardRef } from "react";
+
+type SurfaceToken = "background" | "surface" | "surface-raised" | "surface-sunken" | "muted";
+type MinHeightValue = "viewport" | "full";
+
+export interface PageProps {
+  /** Background color token. */
+  bg?: SurfaceToken;
+  /** Minimum height. */
+  minHeight?: MinHeightValue;
+  /** Additional CSS class names. */
+  className?: string;
+  /** Children elements. */
+  children?: React.ReactNode;
+}
+
+/**
+ * React wrapper for ds-page Web Component.
+ */
+export const Page = forwardRef<HTMLElement, PageProps>((props, ref) => {
+  const { bg = "background", minHeight = "viewport", className, children, ...rest } = props;
+
+  return createElement(
+    "ds-page",
+    {
+      ref,
+      bg,
+      "min-height": minHeight,
+      class: className,
+      ...rest,
+    },
+    children
+  );
+});
+
+Page.displayName = "Page";

package/templates/layout/section.tsx

@@ -0,0 +1,39 @@
+/**
+ * Section React Component
+ *
+ * Semantic section wrapper with consistent vertical spacing.
+ */
+
+import type React from "react";
+import { createElement, forwardRef } from "react";
+
+type SpacingToken = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";
+
+export interface SectionProps {
+  /** Vertical padding. */
+  spacing?: SpacingToken;
+  /** Additional CSS class names. */
+  className?: string;
+  /** Children elements. */
+  children?: React.ReactNode;
+}
+
+/**
+ * React wrapper for ds-section Web Component.
+ */
+export const Section = forwardRef<HTMLElement, SectionProps>((props, ref) => {
+  const { spacing = "lg", className, children, ...rest } = props;
+
+  return createElement(
+    "ds-section",
+    {
+      ref,
+      spacing,
+      class: className,
+      ...rest,
+    },
+    children
+  );
+});
+
+Section.displayName = "Section";

package/templates/layout/spacer.tsx

@@ -0,0 +1,30 @@
+import { createElement, forwardRef } from "react";
+
+type SpacingToken = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";
+type SpacerAxis = "horizontal" | "vertical";
+
+export interface SpacerProps {
+  /** Size of the space. */
+  size?: SpacingToken;
+  /** Axis direction. */
+  axis?: SpacerAxis;
+  /** Additional CSS class names. */
+  className?: string;
+}
+
+/**
+ * React wrapper for ds-spacer Web Component.
+ */
+export const Spacer = forwardRef<HTMLElement, SpacerProps>((props, ref) => {
+  const { size = "md", axis = "vertical", className, ...rest } = props;
+
+  return createElement("ds-spacer", {
+    ref,
+    size,
+    axis,
+    class: className,
+    ...rest,
+  });
+});
+
+Spacer.displayName = "Spacer";

package/templates/layout/split.tsx

@@ -0,0 +1,47 @@
+/**
+ * Split React Component
+ *
+ * Two-region layout with collapse breakpoint.
+ */
+
+import type React from "react";
+import { createElement, forwardRef } from "react";
+
+type BreakpointToken = "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";
+type SpacingToken = "none" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";
+type SplitRatio = "equal" | "1:2" | "2:1" | "1:3" | "3:1";
+
+export interface SplitProps {
+  /** Breakpoint at which to collapse to single column. */
+  collapseAt?: BreakpointToken;
+  /** Gap between regions. */
+  gap?: SpacingToken;
+  /** Width ratio between regions. */
+  ratio?: SplitRatio;
+  /** Additional CSS class names. */
+  className?: string;
+  /** Children elements (should be exactly 2). */
+  children?: React.ReactNode;
+}
+
+/**
+ * React wrapper for ds-split Web Component.
+ */
+export const Split = forwardRef<HTMLElement, SplitProps>((props, ref) => {
+  const { collapseAt = "md", gap = "md", ratio = "equal", className, children, ...rest } = props;
+
+  return createElement(
+    "ds-split",
+    {
+      ref,
+      "collapse-at": collapseAt,
+      gap,
+      ratio,
+      class: className,
+      ...rest,
+    },
+    children
+  );
+});
+
+Split.displayName = "Split";