@xmachines/play-router 1.0.0-beta.1

package/examples/shared/src/styles/layout.css

@@ -0,0 +1,413 @@
+/**
+ * Layout CSS - XMachines Play Demo Applications
+ * 
+ * Purpose: Common layout patterns for standardized UI structure
+ * Usage: Import after tokens.css and reset.css
+ * 
+ * This is a TEMPLATE file - copy to your demo's src/styles/ directory
+ * 
+ * IMPORTANT: This file uses design tokens (CSS custom properties) from tokens.css
+ * Ensure tokens.css is imported BEFORE this file in your stylesheet cascade
+ * 
+ * See: .planning/demos/UI-SPEC.md for complete specification
+ */
+
+/* ========================================
+   APPLICATION CONTAINER
+   ======================================== */
+
+/**
+ * Root application container
+ * Flex column layout ensures header, content, and footer stack vertically
+ * min-height: 100vh fills viewport even when content is short
+ * padding-bottom accounts for fixed debug panel at bottom
+ */
+.demo-app {
+	display: flex;
+	flex-direction: column;
+	min-height: 100vh;
+	padding-bottom: var(--debug-panel-height);
+}
+
+/* ========================================
+   HEADER
+   ======================================== */
+
+/**
+ * Top header bar containing title and navigation
+ * Fixed height ensures consistent layout across all views
+ * Border bottom provides visual separation from content
+ */
+.demo-header {
+	background: var(--color-bg);
+	border-bottom: var(--border-width) solid var(--color-border);
+	padding: var(--space-md) var(--space-lg);
+	display: flex;
+	justify-content: space-between;
+	align-items: center;
+	gap: var(--space-md);
+	height: var(--header-height);
+}
+
+/**
+ * Application title (e.g., "XMachines Play - React Demo")
+ */
+.demo-title {
+	font-size: var(--font-size-h1);
+	font-weight: var(--font-weight-semibold);
+	line-height: var(--line-height-tight);
+	color: var(--color-text);
+	margin: 0;
+}
+
+/* ========================================
+   NAVIGATION
+   ======================================== */
+
+/**
+ * Navigation container
+ * Contains both links (for route navigation) and buttons (for state events)
+ */
+.demo-nav {
+	display: flex;
+	gap: var(--space-md);
+	align-items: center;
+}
+
+/**
+ * Common styling for navigation items (links and buttons)
+ * Base padding, border radius, and hover transitions
+ */
+.demo-nav a,
+.demo-nav button {
+	padding: var(--space-sm) var(--space-md);
+	border-radius: var(--border-radius);
+	font-weight: var(--font-weight-semibold);
+	cursor: pointer;
+	transition: background-color 0.15s ease;
+}
+
+/**
+ * Links - Used for route navigation (Home, Login, Profile)
+ * Semantic HTML: <a> elements represent navigation between routes
+ */
+.demo-nav a {
+	color: var(--color-text);
+	text-decoration: none;
+	background: transparent;
+	border: var(--border-width) solid var(--color-border);
+}
+
+.demo-nav a:hover {
+	background: var(--color-bg-secondary);
+	text-decoration: none;
+}
+
+/**
+ * Active route link styling
+ * Accent color background indicates current route
+ */
+.demo-nav a.active {
+	background: var(--color-accent);
+	color: white;
+	border-color: var(--color-accent);
+}
+
+/**
+ * Buttons - Used for state events (Logout, Submit)
+ * Semantic HTML: <button> elements represent actions/events
+ */
+.demo-nav button {
+	background: var(--color-bg);
+	border: var(--border-width) solid var(--color-border);
+	color: var(--color-text);
+}
+
+.demo-nav button:hover {
+	background: var(--color-bg-secondary);
+}
+
+/**
+ * Primary button variant (typically for main actions)
+ */
+.demo-nav button.primary {
+	background: var(--color-accent);
+	color: white;
+	border-color: var(--color-accent);
+}
+
+.demo-nav button.primary:hover {
+	background: var(--color-accent-hover);
+}
+
+/* ========================================
+   MAIN CONTENT AREA
+   ======================================== */
+
+/**
+ * Main content container
+ * flex: 1 fills remaining vertical space
+ * max-width and auto margins center content on wide screens
+ */
+.demo-content {
+	flex: 1;
+	padding: var(--space-lg);
+	max-width: 1200px;
+	width: 100%;
+	margin: 0 auto;
+}
+
+/* ========================================
+   VIEW CONTAINERS
+   ======================================== */
+
+/**
+ * Generic container for view content
+ * Provides consistent card-like appearance across views
+ */
+.view-container {
+	background: var(--color-bg);
+	border: var(--border-width) solid var(--color-border);
+	border-radius: var(--border-radius);
+	padding: var(--space-lg);
+	margin-bottom: var(--space-lg);
+}
+
+.view-container h2 {
+	font-size: var(--font-size-h2);
+	font-weight: var(--font-weight-semibold);
+	margin-bottom: var(--space-md);
+	color: var(--color-text);
+}
+
+/* ========================================
+   FORMS
+   ======================================== */
+
+/**
+ * Form group pattern (label + input pairing)
+ * Consistent spacing for form fields
+ */
+.form-group {
+	margin-bottom: var(--space-md);
+}
+
+.form-group label {
+	display: block;
+	font-weight: var(--font-weight-semibold);
+	margin-bottom: var(--space-xs);
+	color: var(--color-text);
+}
+
+.form-group input {
+	width: 100%;
+	padding: var(--space-sm) var(--space-md);
+	border: var(--border-width) solid var(--color-border);
+	border-radius: var(--border-radius);
+	font-size: var(--font-size-base);
+	background: var(--color-bg);
+	color: var(--color-text);
+}
+
+/**
+ * Input focus state
+ * Accent color border with subtle shadow for visual feedback
+ */
+.form-group input:focus {
+	outline: none;
+	border-color: var(--color-accent);
+	box-shadow: 0 0 0 3px rgba(20, 184, 166, 0.1);
+}
+
+/**
+ * Form actions container (Submit, Cancel buttons)
+ * Horizontal layout with spacing between buttons
+ */
+.form-actions {
+	display: flex;
+	gap: var(--space-md);
+	margin-top: var(--space-lg);
+}
+
+/* ========================================
+   STATUS DISPLAYS
+   ======================================== */
+
+/**
+ * Status card for displaying information
+ * Secondary background differentiates from main content
+ */
+.status-card {
+	background: var(--color-bg-secondary);
+	border: var(--border-width) solid var(--color-border);
+	border-radius: var(--border-radius);
+	padding: var(--space-md);
+	margin-bottom: var(--space-md);
+}
+
+.status-card p {
+	margin: 0;
+	color: var(--color-text);
+}
+
+/**
+ * Emphasized text within status cards
+ * Accent color highlights important values
+ */
+.status-card strong {
+	color: var(--color-accent);
+	font-weight: var(--font-weight-semibold);
+}
+
+/* ========================================
+   DEBUG PANEL (FIXED FOOTER)
+   ======================================== */
+
+/**
+ * Fixed position debug panel at bottom of viewport
+ * Shows: State ID, Auth status, Current route
+ * Always visible for development/demonstration purposes
+ */
+.demo-debug {
+	position: fixed;
+	bottom: 0;
+	left: 0;
+	right: 0;
+	background: var(--color-bg-secondary);
+	border-top: var(--border-width) solid var(--color-border);
+	padding: var(--space-md);
+	font-size: var(--font-size-small);
+	max-height: var(--debug-panel-height);
+	overflow-y: auto;
+	z-index: 1000;
+}
+
+/**
+ * Debug panel heading
+ * Muted color indicates secondary/meta information
+ */
+.debug-title {
+	font-size: var(--font-size-base);
+	font-weight: var(--font-weight-semibold);
+	margin-bottom: var(--space-sm);
+	color: var(--color-muted);
+}
+
+/**
+ * Debug state container
+ * Horizontal layout with wrapping for narrow viewports
+ */
+.debug-state {
+	display: flex;
+	gap: var(--space-md);
+	flex-wrap: wrap;
+}
+
+/**
+ * Individual debug item (State: X, Auth: Y, Route: Z)
+ */
+.debug-item {
+	display: flex;
+	align-items: center;
+	gap: var(--space-xs);
+}
+
+/**
+ * Debug value styling
+ * <code> elements use accent color for visual emphasis
+ * Monospace font distinguishes values from labels
+ */
+.debug-item code {
+	color: var(--color-accent);
+	font-weight: var(--font-weight-semibold);
+}
+
+/* ========================================
+   BUTTON COMPONENT
+   ======================================== */
+
+/**
+ * Generic button styling (not in navigation)
+ * Use for forms, actions within content areas
+ */
+.button {
+	padding: var(--space-sm) var(--space-md);
+	border: var(--border-width) solid var(--color-border);
+	border-radius: var(--border-radius);
+	background: var(--color-bg);
+	color: var(--color-text);
+	cursor: pointer;
+	font-weight: var(--font-weight-semibold);
+	font-size: var(--font-size-base);
+	transition: background-color 0.15s ease;
+}
+
+.button:hover {
+	background: var(--color-bg-secondary);
+}
+
+/**
+ * Primary button variant
+ * Accent color for main call-to-action
+ */
+.button.primary {
+	background: var(--color-accent);
+	color: white;
+	border-color: var(--color-accent);
+}
+
+.button.primary:hover {
+	background: var(--color-accent-hover);
+}
+
+/**
+ * Disabled button state
+ * Reduced opacity and no pointer cursor
+ */
+.button:disabled {
+	opacity: 0.5;
+	cursor: not-allowed;
+}
+
+.button:disabled:hover {
+	background: var(--color-bg);
+}
+
+.button.primary:disabled:hover {
+	background: var(--color-accent);
+}
+
+/* ========================================
+   USAGE NOTES
+   ======================================== */
+
+/**
+ * Import Order (critical):
+ * 1. tokens.css    (defines CSS custom properties)
+ * 2. reset.css     (normalizes browser defaults)
+ * 3. layout.css    (this file - uses tokens)
+ * 
+ * Framework-Specific Imports:
+ * 
+ * React:
+ *   import './styles/tokens.css';
+ *   import './styles/reset.css';
+ *   import './styles/layout.css';
+ * 
+ * Vue:
+ *   <style>
+ *   @import './styles/tokens.css';
+ *   @import './styles/reset.css';
+ *   @import './styles/layout.css';
+ *   </style>
+ * 
+ * Vanilla:
+ *   import './styles/tokens.css';
+ *   import './styles/reset.css';
+ *   import './styles/layout.css';
+ * 
+ * Customization:
+ * - Override specific classes in your demo's custom CSS
+ * - DO NOT modify token values in components (use tokens.css)
+ * - Add demo-specific styles AFTER this file in cascade
+ */

package/examples/shared/src/styles/reset.css

@@ -0,0 +1,42 @@
+* {
+	box-sizing: border-box;
+	margin: 0;
+	padding: 0;
+}
+
+body {
+	font-family: var(--font-family);
+	font-size: var(--font-size-base);
+	line-height: var(--line-height-base);
+	color: var(--color-text);
+	background: var(--color-bg);
+	-webkit-font-smoothing: antialiased;
+	-moz-osx-font-smoothing: grayscale;
+}
+
+button,
+input,
+select,
+textarea {
+	font-family: inherit;
+	font-size: inherit;
+	line-height: inherit;
+}
+
+a {
+	color: var(--color-accent);
+	text-decoration: none;
+}
+
+a:hover {
+	color: var(--color-accent-hover);
+	text-decoration: underline;
+}
+
+code {
+	font-family: "Monaco", "Courier New", monospace;
+	font-size: 0.9em;
+	background: var(--color-bg-secondary);
+	padding: 0.125rem 0.25rem;
+	border-radius: var(--border-radius);
+}

package/examples/shared/src/styles/tokens.css

@@ -0,0 +1,183 @@
+/**
+ * Design Tokens - XMachines Play Demo Applications
+ * 
+ * Purpose: CSS Custom Properties defining all design values (colors, spacing, typography)
+ * Usage: Import first in your application's stylesheet cascade
+ * 
+ * This is a TEMPLATE file - copy to your demo's src/styles/ directory
+ * 
+ * DO NOT modify token values without updating all 5 demos to maintain consistency
+ * See: .planning/demos/UI-SPEC.md for complete specification
+ */
+
+:root {
+	/* ========================================
+     COLORS
+     ======================================== */
+
+	/**
+   * Base Colors
+   * Used for backgrounds, text, and borders throughout the application
+   */
+	--color-bg: #ffffff; /* Primary background (white) */
+	--color-text: #1a1a1a; /* Primary text color (near black) */
+	--color-border: #e0e0e0; /* Border color (light gray) */
+
+	/**
+   * Accent Colors (Teal)
+   * Primary brand/accent color for interactive elements and active states
+   */
+	--color-accent: #14b8a6; /* teal-500 - Primary accent */
+	--color-accent-hover: #0d9488; /* teal-600 - Hover state for accent */
+
+	/**
+   * Semantic Colors
+   * Colors with specific meaning (errors, muted content, secondary backgrounds)
+   */
+	--color-error: #dc2626; /* red-600 - Error states */
+	--color-muted: #737373; /* gray-500 - Muted/secondary text */
+	--color-bg-secondary: #f5f5f5; /* gray-100 - Secondary backgrounds */
+
+	/* ========================================
+     SPACING (8px base unit)
+     ======================================== */
+
+	/**
+   * Spacing Scale
+   * All spacing values follow 8px base unit system
+   * Use these for padding, margin, gaps between elements
+   */
+	--space-xs: 0.25rem; /* 4px  - Tight spacing, icon gaps */
+	--space-sm: 0.5rem; /* 8px  - Small padding, minimal gaps */
+	--space-md: 1rem; /* 16px - Standard padding, form gaps */
+	--space-lg: 1.5rem; /* 24px - Section spacing, content padding */
+	--space-xl: 2rem; /* 32px - Large section spacing */
+
+	/* ========================================
+     TYPOGRAPHY
+     ======================================== */
+
+	/**
+   * Font Family - System Font Stack
+   * Uses system fonts for zero latency and consistent native appearance
+   * Respects OS font preferences (SF Pro on macOS, Segoe UI on Windows, etc.)
+   */
+	--font-family:
+		-apple-system, BlinkMacSystemFont, "Segoe UI", "Roboto", "Oxygen", "Ubuntu", "Cantarell",
+		"Fira Sans", "Droid Sans", "Helvetica Neue", sans-serif;
+
+	/**
+   * Font Sizes
+   * Base size is 16px (1rem), all other sizes are relative
+   */
+	--font-size-base: 1rem; /* 16px - Body text, buttons, inputs */
+	--font-size-small: 0.875rem; /* 14px - Small text, debug panel */
+	--font-size-large: 1.25rem; /* 20px - Large body text */
+	--font-size-h1: 1.5rem; /* 24px - Page titles (demo-title) */
+	--font-size-h2: 1.25rem; /* 20px - Section headings */
+
+	/**
+   * Line Heights
+   * Base: 1.5 for comfortable reading
+   * Tight: 1.2 for headings where compact text is desired
+   */
+	--line-height-base: 1.5;
+	--line-height-tight: 1.2;
+
+	/**
+   * Font Weights
+   * Normal: 400 for body text
+   * Semibold: 600 for emphasis, headings, buttons
+   */
+	--font-weight-normal: 400;
+	--font-weight-semibold: 600;
+
+	/* ========================================
+     LAYOUT CONSTANTS
+     ======================================== */
+
+	/**
+   * Border Styling
+   * Consistent border radius and width across all elements
+   */
+	--border-radius: 4px;
+	--border-width: 1px;
+
+	/**
+   * Layout Heights
+   * Fixed heights for header and debug panel ensure consistent layout
+   */
+	--header-height: 60px;
+	--debug-panel-height: 200px;
+}
+
+/* ========================================
+   USAGE EXAMPLES
+   ======================================== */
+
+/**
+ * Example: Button with design tokens
+ * 
+ * .button {
+ *   padding: var(--space-sm) var(--space-md);
+ *   background: var(--color-accent);
+ *   color: white;
+ *   border-radius: var(--border-radius);
+ *   font-weight: var(--font-weight-semibold);
+ *   border: none;
+ *   cursor: pointer;
+ * }
+ * 
+ * .button:hover {
+ *   background: var(--color-accent-hover);
+ * }
+ */
+
+/**
+ * Example: Card with consistent spacing
+ * 
+ * .card {
+ *   background: var(--color-bg);
+ *   border: var(--border-width) solid var(--color-border);
+ *   border-radius: var(--border-radius);
+ *   padding: var(--space-lg);
+ *   margin-bottom: var(--space-md);
+ * }
+ */
+
+/**
+ * Example: Typography using tokens
+ * 
+ * h1 {
+ *   font-size: var(--font-size-h1);
+ *   font-weight: var(--font-weight-semibold);
+ *   line-height: var(--line-height-tight);
+ *   color: var(--color-text);
+ *   margin-bottom: var(--space-md);
+ * }
+ */
+
+/* ========================================
+   IMPORTANT NOTES
+   ======================================== */
+
+/**
+ * 1. ALWAYS use var() to reference tokens - never hardcode values
+ *    ✅ CORRECT: color: var(--color-accent);
+ *    ❌ WRONG:   color: #14b8a6;
+ * 
+ * 2. This file should be imported FIRST in your stylesheet cascade
+ *    It defines variables that other stylesheets depend on
+ * 
+ * 3. Browser support: IE 11+ (excellent support across all modern browsers)
+ *    Fallback pattern if needed: color: #14b8a6; color: var(--color-accent);
+ * 
+ * 4. Token modifications:
+ *    - To change a value globally: Modify the token definition here
+ *    - To override for specific demo: Use new token in that demo's CSS
+ *    - To maintain consistency: Update all 5 demos simultaneously
+ * 
+ * 5. Runtime theming:
+ *    CSS Custom Properties can be modified via JavaScript if needed:
+ *    document.documentElement.style.setProperty('--color-accent', '#0ea5e9');
+ */

package/examples/shared/tsconfig.json

@@ -0,0 +1,14 @@
+{
+  "extends": "@xmachines/shared/tsconfig",
+  "compilerOptions": {
+    "composite": true,
+    "rootDir": "./src",
+    "outDir": "./dist"
+  },
+  "references": [
+    { "path": "../../../play-xstate" },
+    { "path": "../.." },
+    { "path": "../../../play-catalog" }
+  ],
+  "include": ["src/**/*"]
+}