@almadar/cli 0.3.2 → 0.3.3

package/shells/typescript-shell/packages/client/src/components/atoms/Typography.tsx

@@ -0,0 +1,207 @@
+/**
+ * Typography Atom Component
+ *
+ * Text elements following the KFlow design system with theme-aware styling.
+ */
+
+import React from "react";
+import { cn } from "../../lib/cn";
+
+export type TypographyVariant =
+  | "h1"
+  | "h2"
+  | "h3"
+  | "h4"
+  | "h5"
+  | "h6"
+  | "body1"
+  | "body2"
+  | "body"
+  | "caption"
+  | "overline"
+  | "small"
+  | "large"
+  | "label";
+
+export type TypographySize = "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";
+
+export interface TypographyProps {
+  /** Typography variant */
+  variant?: TypographyVariant;
+  /** Heading level (1-6) - alternative to variant for headings */
+  level?: 1 | 2 | 3 | 4 | 5 | 6;
+  /** Text color */
+  color?:
+    | "primary"
+    | "secondary"
+    | "muted"
+    | "error"
+    | "success"
+    | "warning"
+    | "inherit";
+  /** Text alignment */
+  align?: "left" | "center" | "right";
+  /** Font weight override */
+  weight?: "light" | "normal" | "medium" | "semibold" | "bold";
+  /** Font size override */
+  size?: TypographySize;
+  /** Truncate with ellipsis */
+  truncate?: boolean;
+  /** Custom HTML element */
+  as?: keyof JSX.IntrinsicElements;
+  /** HTML id attribute */
+  id?: string;
+  /** Additional class names */
+  className?: string;
+  /** Inline style */
+  style?: React.CSSProperties;
+  /** Text content (alternative to children) */
+  content?: React.ReactNode;
+  /** Children elements */
+  children?: React.ReactNode;
+}
+
+// Using CSS variables for theme-aware styling
+const variantStyles: Record<TypographyVariant, string> = {
+  h1: "text-4xl font-bold tracking-tight text-[var(--color-foreground)]",
+  h2: "text-3xl font-bold tracking-tight text-[var(--color-foreground)]",
+  h3: "text-2xl font-bold text-[var(--color-foreground)]",
+  h4: "text-xl font-bold text-[var(--color-foreground)]",
+  h5: "text-lg font-bold text-[var(--color-foreground)]",
+  h6: "text-base font-bold text-[var(--color-foreground)]",
+  body1: "text-base font-normal text-[var(--color-foreground)]",
+  body2: "text-sm font-normal text-[var(--color-foreground)]",
+  body: "text-base font-normal text-[var(--color-foreground)]",
+  caption: "text-xs font-normal text-[var(--color-muted-foreground)]",
+  overline:
+    "text-xs uppercase tracking-wide font-bold text-[var(--color-muted-foreground)]",
+  small: "text-sm font-normal text-[var(--color-foreground)]",
+  large: "text-lg font-medium text-[var(--color-foreground)]",
+  label: "text-sm font-medium text-[var(--color-foreground)]",
+};
+
+const colorStyles = {
+  primary: "text-[var(--color-foreground)]",
+  secondary: "text-[var(--color-muted-foreground)]",
+  muted: "text-[var(--color-muted-foreground)]",
+  error: "text-[var(--color-error)]",
+  success: "text-[var(--color-success)]",
+  warning: "text-[var(--color-warning)]",
+  inherit: "text-inherit",
+};
+
+const weightStyles = {
+  light: "font-light",
+  normal: "font-normal",
+  medium: "font-medium",
+  semibold: "font-semibold",
+  bold: "font-bold",
+};
+
+const defaultElements: Record<TypographyVariant, keyof JSX.IntrinsicElements> =
+  {
+    h1: "h1",
+    h2: "h2",
+    h3: "h3",
+    h4: "h4",
+    h5: "h5",
+    h6: "h6",
+    body1: "p",
+    body2: "p",
+    body: "p",
+    caption: "span",
+    overline: "span",
+    small: "span",
+    large: "p",
+    label: "span",
+  };
+
+const typographySizeStyles: Record<TypographySize, string> = {
+  xs: "text-xs",
+  sm: "text-sm",
+  md: "text-base",
+  lg: "text-lg",
+  xl: "text-xl",
+  "2xl": "text-2xl",
+  "3xl": "text-3xl",
+};
+
+export const Typography: React.FC<TypographyProps> = ({
+  variant: variantProp,
+  level,
+  color = "primary",
+  align,
+  weight,
+  size,
+  truncate = false,
+  as,
+  id,
+  className,
+  style,
+  content,
+  children,
+}) => {
+  // Determine variant: explicit variant takes precedence, then level, then default
+  const variant: TypographyVariant =
+    variantProp ?? (level ? (`h${level}` as TypographyVariant) : "body1");
+  const Component = as || defaultElements[variant];
+
+  return (
+    <Component
+      id={id}
+      className={cn(
+        variantStyles[variant],
+        colorStyles[color],
+        weight && weightStyles[weight],
+        size && typographySizeStyles[size],
+        align && `text-${align}`,
+        truncate && "truncate",
+        className,
+      )}
+      style={style}
+    >
+      {children ?? content}
+    </Component>
+  );
+};
+
+Typography.displayName = "Typography";
+
+/**
+ * Heading component - convenience wrapper for Typography heading variants
+ */
+export interface HeadingProps extends Omit<TypographyProps, "variant"> {
+  /** Heading level (1-6) */
+  level?: 1 | 2 | 3 | 4 | 5 | 6;
+  /** Override font size */
+  size?: "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";
+}
+
+const sizeStyles: Record<string, string> = {
+  xs: "text-xs",
+  sm: "text-sm",
+  md: "text-base",
+  lg: "text-lg",
+  xl: "text-xl",
+  "2xl": "text-2xl",
+  "3xl": "text-3xl",
+};
+
+export const Heading: React.FC<HeadingProps> = ({
+  level = 2,
+  size,
+  className,
+  ...props
+}) => {
+  const variant = `h${level}` as TypographyVariant;
+  const sizeClass = size ? sizeStyles[size] : undefined;
+  return (
+    <Typography
+      variant={variant}
+      className={cn(sizeClass, className)}
+      {...props}
+    />
+  );
+};
+
+Heading.displayName = "Heading";

package/shells/typescript-shell/packages/client/src/components/atoms/game/ControlButton.tsx

@@ -0,0 +1,118 @@
+import * as React from 'react';
+import { cn } from '../../../lib/cn';
+
+export interface ControlButtonProps {
+  /** Button label text */
+  label?: string;
+  /** Icon component or emoji */
+  icon?: React.ReactNode;
+  /** Size variant */
+  size?: 'sm' | 'md' | 'lg' | 'xl' | string;
+  /** Shape variant */
+  shape?: 'circle' | 'rounded' | 'square' | string;
+  /** Visual variant */
+  variant?: 'primary' | 'secondary' | 'ghost' | string;
+  /** Called when button is pressed */
+  onPress?: () => void;
+  /** Called when button is released */
+  onRelease?: () => void;
+  /** Whether the button is currently pressed */
+  pressed?: boolean;
+  /** Whether the button is disabled */
+  disabled?: boolean;
+  /** Additional CSS classes */
+  className?: string;
+}
+
+const sizeMap = {
+  sm: 'w-10 h-10 text-sm',
+  md: 'w-14 h-14 text-base',
+  lg: 'w-18 h-18 text-lg',
+  xl: 'w-24 h-24 text-xl',
+};
+
+const shapeMap = {
+  circle: 'rounded-full',
+  rounded: 'rounded-xl',
+  square: 'rounded-md',
+};
+
+const variantMap = {
+  primary: 'bg-blue-600 text-white border-blue-400 hover:bg-blue-500',
+  secondary: 'bg-gray-700 text-white border-gray-500 hover:bg-gray-600',
+  ghost: 'bg-transparent text-white border-white/30 hover:bg-white/10',
+};
+
+export function ControlButton({
+  label,
+  icon,
+  size = 'md',
+  shape = 'circle',
+  variant = 'secondary',
+  onPress,
+  onRelease,
+  pressed,
+  disabled,
+  className,
+}: ControlButtonProps) {
+  const [isPressed, setIsPressed] = React.useState(false);
+  const actualPressed = pressed ?? isPressed;
+
+  const handlePointerDown = React.useCallback(
+    (e: React.PointerEvent) => {
+      e.preventDefault();
+      if (disabled) return;
+      setIsPressed(true);
+      onPress?.();
+    },
+    [disabled, onPress]
+  );
+
+  const handlePointerUp = React.useCallback(
+    (e: React.PointerEvent) => {
+      e.preventDefault();
+      if (disabled) return;
+      setIsPressed(false);
+      onRelease?.();
+    },
+    [disabled, onRelease]
+  );
+
+  const handlePointerLeave = React.useCallback(
+    (e: React.PointerEvent) => {
+      if (isPressed) {
+        setIsPressed(false);
+        onRelease?.();
+      }
+    },
+    [isPressed, onRelease]
+  );
+
+  return (
+    <button
+      type="button"
+      disabled={disabled}
+      onPointerDown={handlePointerDown}
+      onPointerUp={handlePointerUp}
+      onPointerLeave={handlePointerLeave}
+      onContextMenu={(e) => e.preventDefault()}
+      className={cn(
+        'flex items-center justify-center border-2 font-bold',
+        'select-none touch-none',
+        'transition-all duration-100',
+        'active:scale-95',
+        sizeMap[size as keyof typeof sizeMap] ?? sizeMap.md,
+        shapeMap[shape as keyof typeof shapeMap] ?? shapeMap.circle,
+        variantMap[variant as keyof typeof variantMap] ?? variantMap.secondary,
+        actualPressed && 'scale-95 brightness-110 border-white',
+        disabled && 'opacity-50 cursor-not-allowed',
+        className
+      )}
+    >
+      {icon && <span className="text-2xl">{icon}</span>}
+      {label && !icon && <span>{label}</span>}
+    </button>
+  );
+}
+
+ControlButton.displayName = 'ControlButton';

package/shells/typescript-shell/packages/client/src/components/atoms/game/HealthBar.tsx

@@ -0,0 +1,93 @@
+import * as React from 'react';
+import { cn } from '../../../lib/cn';
+
+export interface HealthBarProps {
+  /** Current health value */
+  current: number;
+  /** Maximum health value */
+  max: number;
+  /** Display format */
+  format?: 'hearts' | 'bar' | 'numeric';
+  /** Size variant */
+  size?: 'sm' | 'md' | 'lg';
+  /** Additional CSS classes */
+  className?: string;
+  /** Animation on change */
+  animated?: boolean;
+}
+
+const heartIcon = (filled: boolean, size: string) => (
+  <svg
+    className={cn('transition-all duration-200', size, filled ? 'text-red-500' : 'text-gray-400')}
+    viewBox="0 0 24 24"
+    fill={filled ? 'currentColor' : 'none'}
+    stroke="currentColor"
+    strokeWidth={filled ? 0 : 2}
+  >
+    <path d="M12 21.35l-1.45-1.32C5.4 15.36 2 12.28 2 8.5 2 5.42 4.42 3 7.5 3c1.74 0 3.41.81 4.5 2.09C13.09 3.81 14.76 3 16.5 3 19.58 3 22 5.42 22 8.5c0 3.78-3.4 6.86-8.55 11.54L12 21.35z" />
+  </svg>
+);
+
+const sizeMap = {
+  sm: { heart: 'w-4 h-4', bar: 'h-2', text: 'text-sm' },
+  md: { heart: 'w-6 h-6', bar: 'h-3', text: 'text-base' },
+  lg: { heart: 'w-8 h-8', bar: 'h-4', text: 'text-lg' },
+};
+
+export function HealthBar({
+  current,
+  max,
+  format = 'hearts',
+  size = 'md',
+  className,
+  animated = true,
+}: HealthBarProps) {
+  const sizes = sizeMap[size];
+  const percentage = Math.max(0, Math.min(100, (current / max) * 100));
+
+  if (format === 'hearts') {
+    return (
+      <div className={cn('flex items-center gap-1', className)}>
+        {Array.from({ length: max }).map((_, i) => (
+          <span
+            key={i}
+            className={cn(animated && 'transition-transform hover:scale-110')}
+          >
+            {heartIcon(i < current, sizes.heart)}
+          </span>
+        ))}
+      </div>
+    );
+  }
+
+  if (format === 'bar') {
+    return (
+      <div
+        className={cn(
+          'relative overflow-hidden rounded-full bg-gray-700',
+          sizes.bar,
+          'w-24',
+          className
+        )}
+      >
+        <div
+          className={cn(
+            'absolute inset-y-0 left-0 rounded-full',
+            percentage > 66 ? 'bg-green-500' : percentage > 33 ? 'bg-yellow-500' : 'bg-red-500',
+            animated && 'transition-all duration-300'
+          )}
+          style={{ width: `${percentage}%` }}
+        />
+      </div>
+    );
+  }
+
+  // Numeric format
+  return (
+    <span className={cn('font-mono font-bold', sizes.text, className)}>
+      {current}/{max}
+    </span>
+  );
+}
+
+HealthBar.displayName = 'HealthBar';

package/shells/typescript-shell/packages/client/src/components/atoms/game/ScoreDisplay.tsx

@@ -0,0 +1,86 @@
+import * as React from 'react';
+import { cn } from '../../../lib/cn';
+
+export interface ScoreDisplayProps {
+  /** Current score value */
+  value: number;
+  /** Label to display before score */
+  label?: string;
+  /** Icon component or emoji */
+  icon?: React.ReactNode;
+  /** Size variant */
+  size?: 'sm' | 'md' | 'lg' | 'xl';
+  /** Additional CSS classes */
+  className?: string;
+  /** Animation on value change */
+  animated?: boolean;
+  /** Number formatting locale */
+  locale?: string;
+}
+
+const sizeMap = {
+  sm: 'text-sm',
+  md: 'text-lg',
+  lg: 'text-2xl',
+  xl: 'text-4xl',
+};
+
+export function ScoreDisplay({
+  value,
+  label,
+  icon,
+  size = 'md',
+  className,
+  animated = true,
+  locale = 'en-US',
+}: ScoreDisplayProps) {
+  const [displayValue, setDisplayValue] = React.useState(value);
+  const [isAnimating, setIsAnimating] = React.useState(false);
+
+  React.useEffect(() => {
+    if (!animated || displayValue === value) {
+      setDisplayValue(value);
+      return;
+    }
+
+    setIsAnimating(true);
+    const diff = value - displayValue;
+    const steps = Math.min(Math.abs(diff), 20);
+    const increment = diff / steps;
+    let current = displayValue;
+    let step = 0;
+
+    const timer = setInterval(() => {
+      step++;
+      current += increment;
+      setDisplayValue(Math.round(current));
+
+      if (step >= steps) {
+        clearInterval(timer);
+        setDisplayValue(value);
+        setIsAnimating(false);
+      }
+    }, 50);
+
+    return () => clearInterval(timer);
+  }, [value, animated]);
+
+  const formattedValue = new Intl.NumberFormat(locale).format(displayValue);
+
+  return (
+    <div
+      className={cn(
+        'flex items-center gap-2 font-bold',
+        sizeMap[size],
+        isAnimating && 'animate-pulse',
+        className
+      )}
+    >
+      {icon && <span className="flex-shrink-0">{icon}</span>}
+      {label && <span className="text-gray-400">{label}</span>}
+      <span className="tabular-nums">{formattedValue}</span>
+    </div>
+  );
+}
+
+ScoreDisplay.displayName = 'ScoreDisplay';

package/shells/typescript-shell/packages/client/src/components/atoms/game/Sprite.tsx

@@ -0,0 +1,188 @@
+/**
+ * Sprite Component
+ *
+ * Renders a single frame from a spritesheet with transform support.
+ */
+
+import React, { useMemo } from 'react';
+
+export interface SpriteProps {
+  /** Spritesheet image URL */
+  spritesheet: string;
+  /** Width of each frame in pixels */
+  frameWidth: number;
+  /** Height of each frame in pixels */
+  frameHeight: number;
+  /** Frame index to display (0-based, left-to-right, top-to-bottom) */
+  frame: number;
+  /** X position in pixels */
+  x: number;
+  /** Y position in pixels */
+  y: number;
+  /** Scale factor (default: 1) */
+  scale?: number;
+  /** Flip horizontally */
+  flipX?: boolean;
+  /** Flip vertically */
+  flipY?: boolean;
+  /** Rotation in degrees */
+  rotation?: number;
+  /** Opacity (0-1) */
+  opacity?: number;
+  /** Z-index for layering */
+  zIndex?: number;
+  /** Number of columns in spritesheet (for frame calculation) */
+  columns?: number;
+  /** Optional className */
+  className?: string;
+  /** Optional onClick handler */
+  onClick?: () => void;
+}
+
+/**
+ * Sprite component for rendering spritesheet frames
+ *
+ * @example
+ * ```tsx
+ * <Sprite
+ *   spritesheet="/sprites/player.png"
+ *   frameWidth={32}
+ *   frameHeight={32}
+ *   frame={currentFrame}
+ *   x={player.x}
+ *   y={player.y}
+ *   flipX={player.facingLeft}
+ *   scale={2}
+ * />
+ * ```
+ */
+export function Sprite({
+  spritesheet,
+  frameWidth,
+  frameHeight,
+  frame,
+  x,
+  y,
+  scale = 1,
+  flipX = false,
+  flipY = false,
+  rotation = 0,
+  opacity = 1,
+  zIndex = 0,
+  columns = 16,
+  className,
+  onClick,
+}: SpriteProps): JSX.Element {
+  // Calculate source position in spritesheet
+  const sourcePosition = useMemo(() => {
+    const frameX = frame % columns;
+    const frameY = Math.floor(frame / columns);
+    return {
+      x: frameX * frameWidth,
+      y: frameY * frameHeight,
+    };
+  }, [frame, columns, frameWidth, frameHeight]);
+
+  // Build transform string
+  const transform = useMemo(() => {
+    const transforms: string[] = [
+      `translate(${x}px, ${y}px)`,
+    ];
+
+    if (scale !== 1) {
+      transforms.push(`scale(${scale})`);
+    }
+
+    if (flipX || flipY) {
+      transforms.push(`scale(${flipX ? -1 : 1}, ${flipY ? -1 : 1})`);
+    }
+
+    if (rotation !== 0) {
+      transforms.push(`rotate(${rotation}deg)`);
+    }
+
+    return transforms.join(' ');
+  }, [x, y, scale, flipX, flipY, rotation]);
+
+  // Background position for spritesheet clipping
+  const backgroundPosition = `-${sourcePosition.x}px -${sourcePosition.y}px`;
+
+  return (
+    <div
+      className={className}
+      onClick={onClick}
+      style={{
+        position: 'absolute',
+        width: frameWidth,
+        height: frameHeight,
+        backgroundImage: `url(${spritesheet})`,
+        backgroundPosition,
+        backgroundRepeat: 'no-repeat',
+        imageRendering: 'pixelated',
+        transform,
+        transformOrigin: 'center center',
+        opacity,
+        zIndex,
+        pointerEvents: onClick ? 'auto' : 'none',
+      }}
+    />
+  );
+}
+
+/**
+ * Canvas-based sprite renderer for better performance in game loops
+ */
+export function drawSprite(
+  ctx: CanvasRenderingContext2D,
+  image: HTMLImageElement,
+  props: Omit<SpriteProps, 'spritesheet' | 'className' | 'onClick'>
+): void {
+  const {
+    frameWidth,
+    frameHeight,
+    frame,
+    x,
+    y,
+    scale = 1,
+    flipX = false,
+    flipY = false,
+    rotation = 0,
+    opacity = 1,
+    columns = 16,
+  } = props;
+
+  // Calculate source position
+  const sourceX = (frame % columns) * frameWidth;
+  const sourceY = Math.floor(frame / columns) * frameHeight;
+
+  // Save context state
+  ctx.save();
+
+  // Apply transforms
+  ctx.globalAlpha = opacity;
+  ctx.translate(x + frameWidth / 2, y + frameHeight / 2);
+
+  if (rotation !== 0) {
+    ctx.rotate((rotation * Math.PI) / 180);
+  }
+
+  ctx.scale(scale * (flipX ? -1 : 1), scale * (flipY ? -1 : 1));
+
+  // Draw sprite
+  ctx.drawImage(
+    image,
+    sourceX,
+    sourceY,
+    frameWidth,
+    frameHeight,
+    -frameWidth / 2,
+    -frameHeight / 2,
+    frameWidth,
+    frameHeight
+  );
+
+  // Restore context state
+  ctx.restore();
+}
+
+export default Sprite;

package/shells/typescript-shell/packages/client/src/components/atoms/game/index.ts

@@ -0,0 +1,12 @@
+/**
+ * Game Atom Components
+ *
+ * Basic building blocks for game UI.
+ *
+ * @packageDocumentation
+ */
+
+export { HealthBar, type HealthBarProps } from './HealthBar';
+export { ScoreDisplay, type ScoreDisplayProps } from './ScoreDisplay';
+export { ControlButton, type ControlButtonProps } from './ControlButton';
+export { Sprite, drawSprite, type SpriteProps } from './Sprite';