@backbay/glia-desktop 0.2.0-alpha.1

package/src/components/desktop/SnapZoneOverlay.tsx

@@ -0,0 +1,230 @@
+/**
+ * @backbay/glia Desktop OS - Snap Zone Overlay Component
+ *
+ * Visual feedback overlay showing the target snap zone during window dragging.
+ * Uses CSS variables for theming (--glia-color-*, etc.)
+ */
+
+import React, { useMemo } from 'react';
+import { useSnapZones, getSnapZoneDimensions } from '../../core/desktop/useSnapZones';
+import type { SnapZone } from '../../core/desktop/types';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface SnapZoneOverlayProps {
+  /** Override the active zone (uses hook state by default) */
+  zone?: SnapZone | null;
+  /** Custom color for the overlay */
+  color?: string;
+  /** Additional CSS class */
+  className?: string;
+  /** Inline styles */
+  style?: React.CSSProperties;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Styles (using CSS custom properties)
+// ═══════════════════════════════════════════════════════════════════════════
+
+const containerStyles: React.CSSProperties = {
+  position: 'fixed',
+  inset: 0,
+  pointerEvents: 'none',
+  zIndex: 9998, // Just below windows being dragged
+};
+
+const createPreviewStyles = (
+  dimensions: { x: number; y: number; width: number; height: number },
+  color?: string
+): React.CSSProperties => ({
+  position: 'absolute',
+  left: dimensions.x,
+  top: dimensions.y,
+  width: dimensions.width,
+  height: dimensions.height,
+  background: color ?? 'var(--glia-glass-active-shadow, rgba(212, 168, 75, 0.15))',
+  border: `2px solid ${color ?? 'var(--glia-color-accent, #d4a84b)'}`,
+  borderRadius: 'var(--glia-radius-lg, 3px)',
+  transition: 'all 150ms var(--glia-easing-spring, cubic-bezier(0.34, 1.56, 0.64, 1))',
+  // Add subtle inner glow
+  boxShadow: `
+    inset 0 0 60px 10px ${color ?? 'var(--glia-glass-active-shadow, rgba(212, 168, 75, 0.1))'},
+    0 0 40px 5px ${color ?? 'var(--glia-glass-active-shadow, rgba(212, 168, 75, 0.1))'}
+  `,
+});
+
+// Zone label styles (shows which zone is being targeted)
+const labelStyles: React.CSSProperties = {
+  position: 'absolute',
+  top: '50%',
+  left: '50%',
+  transform: 'translate(-50%, -50%)',
+  fontFamily: 'var(--glia-font-mono, "JetBrains Mono", monospace)',
+  fontSize: '12px',
+  fontWeight: 600,
+  letterSpacing: '0.1em',
+  textTransform: 'uppercase',
+  color: 'var(--glia-color-accent, #d4a84b)',
+  opacity: 0.6,
+  userSelect: 'none',
+  whiteSpace: 'nowrap',
+};
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Helper Functions
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Get human-readable label for snap zone.
+ */
+function getZoneLabel(zone: SnapZone): string {
+  switch (zone) {
+    case 'maximize':
+      return 'Maximize';
+    case 'left':
+      return 'Left Half';
+    case 'right':
+      return 'Right Half';
+    case 'top-left':
+      return 'Top Left';
+    case 'top-right':
+      return 'Top Right';
+    case 'bottom-left':
+      return 'Bottom Left';
+    case 'bottom-right':
+      return 'Bottom Right';
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Component
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Snap zone overlay component.
+ *
+ * Displays a semi-transparent preview rectangle showing where a window
+ * will snap to when released during a drag operation.
+ *
+ * @example Using with hook state (automatic)
+ * ```tsx
+ * const { activeZone } = useSnapZones();
+ *
+ * return (
+ *   <>
+ *     {activeZone && <SnapZoneOverlay />}
+ *   </>
+ * );
+ * ```
+ *
+ * @example Manual control
+ * ```tsx
+ * <SnapZoneOverlay
+ *   zone="left"
+ *   color="rgba(0, 255, 128, 0.2)"
+ * />
+ * ```
+ */
+export function SnapZoneOverlay({
+  zone: zoneProp,
+  color,
+  className,
+  style,
+}: SnapZoneOverlayProps) {
+  const { activeZone: hookZone } = useSnapZones();
+  const zone = zoneProp ?? hookZone;
+
+  // Calculate preview dimensions
+  const dimensions = useMemo(() => {
+    if (!zone) return null;
+    return getSnapZoneDimensions(zone);
+  }, [zone]);
+
+  // Create preview styles
+  const previewStyles = useMemo(() => {
+    if (!dimensions) return null;
+    return createPreviewStyles(dimensions, color);
+  }, [dimensions, color]);
+
+  // Don't render if no active zone
+  if (!zone || !dimensions || !previewStyles) {
+    return null;
+  }
+
+  return (
+    <div
+      className={className}
+      style={{ ...containerStyles, ...style }}
+      data-bb-snap-zone-overlay
+      data-zone={zone}
+    >
+      {/* Preview rectangle */}
+      <div style={previewStyles} data-bb-snap-preview>
+        {/* Zone label */}
+        <span style={labelStyles} data-bb-snap-label>
+          {getZoneLabel(zone)}
+        </span>
+      </div>
+    </div>
+  );
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Standalone Preview (for use without hooks)
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface SnapZonePreviewProps {
+  /** The snap zone to preview */
+  zone: SnapZone;
+  /** Custom color for the overlay */
+  color?: string;
+  /** Whether to show the label */
+  showLabel?: boolean;
+  /** Additional CSS class */
+  className?: string;
+  /** Inline styles */
+  style?: React.CSSProperties;
+}
+
+/**
+ * Standalone snap zone preview without hook dependency.
+ *
+ * Useful for testing or custom implementations.
+ *
+ * @example
+ * ```tsx
+ * <SnapZonePreview zone="left" showLabel={false} />
+ * ```
+ */
+export function SnapZonePreview({
+  zone,
+  color,
+  showLabel = true,
+  className,
+  style,
+}: SnapZonePreviewProps) {
+  const dimensions = useMemo(() => getSnapZoneDimensions(zone), [zone]);
+  const previewStyles = useMemo(
+    () => createPreviewStyles(dimensions, color),
+    [dimensions, color]
+  );
+
+  return (
+    <div
+      className={className}
+      style={{ ...containerStyles, ...style }}
+      data-bb-snap-zone-preview
+      data-zone={zone}
+    >
+      <div style={previewStyles} data-bb-snap-preview>
+        {showLabel && (
+          <span style={labelStyles} data-bb-snap-label>
+            {getZoneLabel(zone)}
+          </span>
+        )}
+      </div>
+    </div>
+  );
+}

package/src/components/desktop/index.ts

@@ -0,0 +1,15 @@
+/**
+ * @backbay/glia Desktop OS - Desktop Components
+ *
+ * Components for the main desktop surface, icons, and snap zones.
+ */
+
+export { Desktop, type DesktopProps } from './Desktop';
+export { DesktopIcon, type DesktopIconProps } from './DesktopIcon';
+export {
+  SnapZoneOverlay,
+  SnapZonePreview,
+  type SnapZoneOverlayProps,
+  type SnapZonePreviewProps,
+} from './SnapZoneOverlay';
+export { FileBrowser } from './FileBrowser';

package/src/components/index.ts

@@ -0,0 +1,16 @@
+/**
+ * @backbay/glia Desktop OS - Components
+ *
+ * Styled UI components for the desktop OS layer.
+ * All components use CSS variables for theming and can work
+ * standalone or within the DesktopOSProvider context.
+ */
+
+// Desktop components (desktop surface, icons, snap zones)
+export * from './desktop';
+
+// Shell components (taskbar, context menu, clock)
+export * from './shell';
+
+// Window components (window container, titlebar)
+export * from './window';

package/src/components/shell/Clock.tsx

@@ -0,0 +1,212 @@
+/**
+ * @backbay/glia Desktop OS - Clock Component
+ *
+ * System clock for the taskbar. Displays time in Roman numerals (Backbay style)
+ * with a tooltip showing the full date on hover.
+ *
+ * Can be used standalone or within the DesktopOSProvider context.
+ *
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <Clock />
+ *
+ * // With custom format
+ * <Clock format="standard" />
+ *
+ * // Styled with CSS variables
+ * <Clock style={{ '--glia-font-mono': 'Monaco, monospace' }} />
+ * ```
+ */
+
+import { useState, useEffect, type CSSProperties } from 'react';
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Types
+// ═══════════════════════════════════════════════════════════════════════════
+
+export interface ClockProps {
+  /** Time display format */
+  format?: 'roman' | 'standard' | '24h';
+  /** Whether to show seconds */
+  showSeconds?: boolean;
+  /** Whether to show date tooltip on hover */
+  showTooltip?: boolean;
+  /** Additional CSS class name */
+  className?: string;
+  /** Additional inline styles */
+  style?: CSSProperties;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Roman Numeral Conversion
+// ═══════════════════════════════════════════════════════════════════════════
+
+const ROMAN_NUMERALS: [number, string][] = [
+  [1000, 'M'],
+  [900, 'CM'],
+  [500, 'D'],
+  [400, 'CD'],
+  [100, 'C'],
+  [90, 'XC'],
+  [50, 'L'],
+  [40, 'XL'],
+  [10, 'X'],
+  [9, 'IX'],
+  [5, 'V'],
+  [4, 'IV'],
+  [1, 'I'],
+];
+
+function toRomanNumeral(num: number): string {
+  if (num <= 0) return 'N'; // nulla (0)
+  let result = '';
+  let remaining = num;
+  for (const [value, symbol] of ROMAN_NUMERALS) {
+    while (remaining >= value) {
+      result += symbol;
+      remaining -= value;
+    }
+  }
+  return result;
+}
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Styles
+// ═══════════════════════════════════════════════════════════════════════════
+
+const styles: Record<string, CSSProperties> = {
+  wrapper: {
+    position: 'relative',
+    display: 'flex',
+    alignItems: 'center',
+    height: '100%',
+  },
+  clock: {
+    fontFamily: 'var(--glia-font-mono)',
+    fontSize: '13px',
+    color: 'var(--glia-color-text-soft)',
+    padding: '0 12px',
+    letterSpacing: '0.05em',
+    cursor: 'default',
+    userSelect: 'none',
+    transition: 'color var(--glia-duration-fast, 100ms) ease',
+  },
+  clockHover: {
+    color: 'var(--glia-color-text-muted)',
+  },
+  tooltip: {
+    position: 'absolute',
+    bottom: '100%',
+    right: 0,
+    marginBottom: '8px',
+    padding: '8px 12px',
+    background: 'var(--glia-color-bg-elevated, #111111)',
+    border: '1px solid var(--glia-color-border, #333333)',
+    borderRadius: 'var(--glia-radius-md, 3px)',
+    fontFamily: 'var(--glia-font-body)',
+    fontSize: '12px',
+    color: 'var(--glia-color-text-muted)',
+    whiteSpace: 'nowrap',
+    boxShadow: 'var(--glia-shadow-soft)',
+    zIndex: 10000,
+  },
+};
+
+// ═══════════════════════════════════════════════════════════════════════════
+// Component
+// ═══════════════════════════════════════════════════════════════════════════
+
+export function Clock({
+  format = 'roman',
+  showSeconds = false,
+  showTooltip: enableTooltip = true,
+  className,
+  style,
+}: ClockProps) {
+  const [time, setTime] = useState<Date | null>(null);
+  const [showTooltip, setShowTooltip] = useState(false);
+  const [isHovered, setIsHovered] = useState(false);
+
+  // Initialize on client side only (SSR-safe)
+  useEffect(() => {
+    setTime(new Date());
+
+    const interval = setInterval(() => {
+      setTime(new Date());
+    }, showSeconds ? 1000 : 60000);
+
+    return () => clearInterval(interval);
+  }, [showSeconds]);
+
+  // Don't render until client-side hydrated
+  if (!time) return null;
+
+  const hours = time.getHours();
+  const minutes = time.getMinutes();
+  const seconds = time.getSeconds();
+
+  let formattedTime: string;
+
+  switch (format) {
+    case 'roman': {
+      const romanHours = toRomanNumeral(hours === 0 ? 24 : hours);
+      const romanMinutes = toRomanNumeral(minutes);
+      formattedTime = showSeconds
+        ? `${romanHours}:${romanMinutes}:${toRomanNumeral(seconds)}`
+        : `${romanHours}:${romanMinutes || 'N'}`;
+      break;
+    }
+    case '24h': {
+      const pad = (n: number) => n.toString().padStart(2, '0');
+      formattedTime = showSeconds
+        ? `${pad(hours)}:${pad(minutes)}:${pad(seconds)}`
+        : `${pad(hours)}:${pad(minutes)}`;
+      break;
+    }
+    case 'standard':
+    default: {
+      const h = hours % 12 || 12;
+      const ampm = hours >= 12 ? 'PM' : 'AM';
+      const pad = (n: number) => n.toString().padStart(2, '0');
+      formattedTime = showSeconds
+        ? `${h}:${pad(minutes)}:${pad(seconds)} ${ampm}`
+        : `${h}:${pad(minutes)} ${ampm}`;
+      break;
+    }
+  }
+
+  const fullDate = time.toLocaleDateString('en-US', {
+    weekday: 'long',
+    year: 'numeric',
+    month: 'long',
+    day: 'numeric',
+  });
+
+  return (
+    <div
+      style={{ ...styles.wrapper, ...style }}
+      className={className}
+      onMouseEnter={() => {
+        setShowTooltip(true);
+        setIsHovered(true);
+      }}
+      onMouseLeave={() => {
+        setShowTooltip(false);
+        setIsHovered(false);
+      }}
+    >
+      <div
+        style={{
+          ...styles.clock,
+          ...(isHovered ? styles.clockHover : {}),
+        }}
+      >
+        {formattedTime}
+      </div>
+      {enableTooltip && showTooltip && (
+        <div style={styles.tooltip}>{fullDate}</div>
+      )}
+    </div>
+  );
+}