@mathscan/math-exercise-engine 1.0.2 → 1.0.3

package/dist/style.css

@@ -1,17 +1,45 @@
-/* ========================================
-   MATH EXERCISE ENGINE - DEFAULT STYLES
-   ========================================
-   Minimal, responsive styles for math-exercise-engine
-   All styles use scoped CSS custom properties for easy theming
-   ======================================== */
-
-/* ========================================
-   MAIN CONTAINER
-   ======================================== */
+/**
+ * Math Exercise Engine - Default Styles
+ *
+ * This file is maintained for backward compatibility.
+ * All styles have been reorganized into modular CSS files.
+ *
+ * New structure: src/renderer/styles/
+ * - variables.css     - CSS custom properties
+ * - layout.css        - Layout & structure
+ * - text.css          - Text content & bidi
+ * - inputs.css        - Input fields
+ * - widgets.css       - Drag options & keypad
+ * - buttons.css       - Submit button
+ * - responsive.css    - Media queries
+ */
+
+/**
+ * Math Exercise Engine - Main Stylesheet
+ *
+ * Modular CSS architecture for maintainability and clarity.
+ *
+ * Import order matters:
+ * 1. Variables (must be first - used by all other modules)
+ * 2. Core layout and structure
+ * 3. Content styles (text, inputs, widgets)
+ * 4. Responsive overrides (must be last to take precedence)
+ */
+
+/* CSS Custom Properties - must be imported first */
+
+/**
+ * CSS Custom Properties (Variables)
+ *
+ * All theming variables for the math exercise renderer.
+ * These can be overridden by consumers for custom themes.
+ */
 
-/* Scoped CSS Custom Properties for Theming */
 .math-exercise-renderer {
-  /* Colors */
+  /* ========================================
+     COLOR VARIABLES
+     ======================================== */
+
   --exercise-bg: white;
   --exercise-text: #333;
   --exercise-text-light: #555;
@@ -21,26 +49,71 @@
   --exercise-border: #ddd;
   --exercise-border-focus: var(--exercise-primary);
 
-  /* Spacing */
+  /* ========================================
+     SPACING VARIABLES
+     ======================================== */
+
+  /** Main container padding - responsive with clamp() */
   --exercise-padding: clamp(1rem, 3vw, 2rem);
+
+  /** Bottom margin for major sections */
   --exercise-margin-bottom: 1.5rem;
+
+  /** Gap between exercise lines (0.25rem = 4px) */
   --exercise-line-gap: 0.25rem;
+
+  /** Margin between inline elements (0.25rem = 4px) */
   --exercise-element-margin: 0.25rem;
 
-  /* Typography */
+  /* ========================================
+     TYPOGRAPHY VARIABLES
+     ======================================== */
+
+  /** Base font size - responsive (14px to 20px) */
   --exercise-font-size: clamp(0.875rem, 2vw, 1.25rem);
+
+  /** Larger font size for inputs/buttons (12px to 16px) */
   --exercise-font-size-large: clamp(1rem, 1.5vw, 0.75rem);
+
+  /** Normal font weight */
   --exercise-font-weight: 500;
+
+  /** Bold font weight */
   --exercise-font-weight-bold: 600;
 
-  /* Layout */
+  /* ========================================
+     LAYOUT VARIABLES
+     ======================================== */
+
+  /** Input field width - responsive (40px to 64px) */
   --exercise-input-width: clamp(2.5rem, 5vw, 4rem);
+
+  /** Input padding (6px 10px) */
   --exercise-input-padding: 0.375rem 0.625rem;
+
+  /** Button width - responsive (48px to 64px) */
   --exercise-button-width: clamp(3rem, 6vw, 4rem);
+
+  /** Border radius for rounded corners */
   --exercise-border-radius: 0.25rem;
+
+  /** Border width for inputs and buttons */
   --exercise-border-width: 2px;
+}
+
+/* Layout & Structure */
+
+/**
+ * Layout & Structure Styles
+ *
+ * Main container and layout grid styles.
+ */
+
+/* ========================================
+   MAIN CONTAINER
+   ======================================== */
 
-  /* Component styles */
+.math-exercise-renderer {
   position: relative;
   background: var(--exercise-bg);
   padding: var(--exercise-padding);
@@ -50,18 +123,25 @@
 }
 
 /* ========================================
-   LAYOUT & STRUCTURE
+   LAYOUT CONTAINER
    ======================================== */
 
 .exercise-layout-container {
-  /* Default: no flex when no keypad */
+  /* Default: regular block layout */
 }
 
 .exercise-layout-container.has-keypad {
+  /* When keypad is present, use flex layout for side-by-side */
   display: flex;
+  justify-content: space-between;
 }
-   
+
+/* ========================================
+   EXERCISE LAYOUT
+   ======================================== */
+
 .exercise-layout {
+  justify-content: space-evenly;
   display: flex;
   flex-direction: column;
   gap: var(--exercise-line-gap);
@@ -69,63 +149,109 @@
   margin-bottom: var(--exercise-margin-bottom);
 }
 
+/* ========================================
+   EXERCISE LINES
+   ======================================== */
+
 .exercise-line {
   display: flex;
   flex-wrap: wrap;
   align-items: center;
   justify-content: center;
+  align-items: baseline;
   gap: var(--exercise-element-margin);
   padding-bottom: calc(var(--exercise-line-gap) * 0.5);
 }
 
 .exercise-line-arabic {
-  /* Arabic text alignment - can be overridden by consuming apps */
-  justify-content: flex-end;
+  /* RTL layout handled by dir="rtl" attribute on text groups */
+  /* No additional styling needed */
 }
 
-.linebreak {
-  /* Line break element - handled by flex layout */
-}
+/* Content Styles */
+
+/**
+ * Text Content Styles
+ *
+ * Styles for text items, questions, operators, and bidirectional text.
+ */
 
 /* ========================================
-   TEXT CONTENT
+   QUESTION TEXT
    ======================================== */
 
 .question-text {
   display: block;
   width: 100%;
-  font-size: calc(var(--exercise-font-size-large) * 1.2);
+  font-size: calc(var(--exercise-font-size-large) * 1);
   font-weight: var(--exercise-font-weight-bold);
   margin-bottom: var(--exercise-margin-bottom);
   color: var(--exercise-text);
   line-height: 1.4;
+  text-align: center;
 }
 
 .question-text-arabic {
-  direction: rtl;
-  text-align: right;
+
 }
 
+/* ========================================
+   TEXT ITEMS
+   ======================================== */
+
 .text-item {
-  margin: 0 var(--exercise-element-margin);
   color: var(--exercise-text);
+  font-size: medium;
+}
+
+.text-group {
+  /**
+   * Wrapper for text segments with bidirectional content.
+   * unicode-bidi: plaintext lets the browser auto-detect direction
+   * based on the first strong directional character.
+   */
+  display: inline;
+  unicode-bidi: plaintext;
 }
 
 .text-item-arabic {
-  text-align: end;
+  /* Direction is handled by parent text-group with unicode-bidi: plaintext */
 }
 
 .text-item-not-arabic {
-  text-align: start;
+  /* Direction is handled by parent text-group with unicode-bidi: plaintext */
 }
 
-.number-text {
+/* ========================================
+   SPACE ELEMENT
+   ======================================== */
+
+.space {
+  /**
+   * Minimal width to create visual spacing between inline elements.
+   * 0.5px is intentionally small - actual spacing comes from flex gap.
+   * This just ensures the element exists in the layout.
+   */
+  width: 0.5px;
+}
+
+/* ========================================
+   HIGHLIGHTED TEXT
+   ======================================== */
+
+.highlighted-text {
   font-weight: var(--exercise-font-weight);
   margin: 0 var(--exercise-element-margin);
   color: var(--exercise-text);
+
+  /**
+   * unicode-bidi: isolate prevents highlighted text from being affected
+   * by parent RTL context, keeping numbers in correct order.
+   */
+  unicode-bidi: isolate;
 }
 
-.number-text .highlight {
+.highlighted-text .highlight {
   color: red;
   font-weight: var(--exercise-font-weight-bold);
 }
@@ -135,10 +261,10 @@
    ======================================== */
 
 .operator {
-  margin: 0 calc(var(--exercise-element-margin) * 2);
-  font-weight: var(--exercise-font-weight-bold);
+  font-weight: 900;
   color: var(--exercise-accent);
-  font-size: var(--exercise-font-size-large);
+  /** Operator size: 20px - larger than text for visual emphasis */
+  font-size: 20px;
 }
 
 .group {
@@ -146,8 +272,14 @@
   color: var(--exercise-text-light);
 }
 
+/**
+ * Input Styles
+ *
+ * Styles for interactive input fields.
+ */
+
 /* ========================================
-   INTERACTIVE ELEMENTS
+   INLINE INPUT
    ======================================== */
 
 .inline-input {
@@ -160,11 +292,18 @@
   transition: border-color 0.2s ease, box-shadow 0.2s ease;
   background: var(--exercise-bg);
   color: var(--exercise-text);
+
+  /**
+   * Always LTR for inputs - even in RTL context, numbers should
+   * be entered left-to-right for consistent UX.
+   */
+  direction: ltr;
 }
 
 .inline-input:focus {
   outline: none;
   border-color: var(--exercise-border-focus);
+  /** Focus shadow: 3px blur with 10% opacity primary color */
   box-shadow: 0 0 0 3px rgba(0, 122, 204, 0.1);
 }
 
@@ -172,14 +311,18 @@
   border-color: var(--exercise-border-focus);
 }
 
+/**
+ * Widget Styles
+ *
+ * Styles for drag options, numeric keypad, and other interactive widgets.
+ */
+
 /* ========================================
-   WIDGETS & TOOLS
+   DRAG OPTIONS
    ======================================== */
 
-/* Drag Options */
 .drag-options-container {
-  /* margin-top: var(--exercise-margin-bottom); */
-  /* padding: var(--exercise-padding); */
+  /* Container for drag options widget */
 }
 
 .drag-options {
@@ -190,6 +333,7 @@
 }
 
 .drag-option {
+  /** Padding: 10px vertical, 16px horizontal for comfortable touch targets */
   padding: 10px 16px;
   border: var(--exercise-border-width) solid var(--exercise-border);
   border-radius: var(--exercise-border-radius);
@@ -206,11 +350,11 @@
 
 .drag-option:hover {
   border-color: var(--exercise-primary);
-  /* background: rgba(0, 122, 204, 0.05); */
 }
 
 .drag-option:active {
   cursor: grabbing;
+  /** Scale down slightly (98%) when dragging for visual feedback */
   transform: scale(0.98);
 }
 
@@ -218,34 +362,45 @@
   background: var(--exercise-primary);
   color: white;
   border-color: var(--exercise-primary);
+  /** Shadow: 2px offset, 4px blur, 20% opacity for depth */
   box-shadow: 0 2px 4px rgba(0, 122, 204, 0.2);
 }
 
-/* Legacy button styles - for backward compatibility */
+/* Legacy button-style drag options for backward compatibility */
+
 button.drag-option {
-  /* padding: calc(var(--exercise-input-padding) * 2); */
   border: none;
   border-radius: var(--exercise-border-radius);
   cursor: pointer;
   font-size: var(--exercise-font-size);
   color: white;
   background: var(--exercise-accent);
-  /* width: var(--exercise-button-width); */
   font-weight: var(--exercise-font-weight);
 }
 
-/* Numeric Keypad */
+/* ========================================
+   NUMERIC KEYPAD
+   ======================================== */
+
+.numeric-keypad-container {
+  /**
+   * Keypad container dimensions:
+   * - min-width: 150px ensures keypad is always usable
+   * - margins: 5px on each side for spacing
+   */
+  min-width: 150px;
+  margin-right: 5px;
+  margin-left: 5px;
+}
+
 .numeric-keypad {
   display: grid;
   grid-template-columns: repeat(3, 1fr);
-  gap: calc(var(--exercise-element-margin) * 1);
-  /* margin-top: var(--exercise-margin-bottom); */
+  gap: var(--exercise-element-margin);
 }
 
-.numeric-keypad-container {
- min-width: 150px;
- margin-right: 5px;
- margin-left: 5px;
+.numeric-keypad-with-operators {
+  grid-template-columns: repeat(4, 1fr);
 }
 
 .keypad-btn {
@@ -266,17 +421,25 @@ button.drag-option {
 
 .keypad-btn:hover {
   border-color: var(--exercise-primary);
+  /** Hover background: 5% opacity primary color */
   background: rgba(0, 122, 204, 0.05);
 }
 
 .keypad-btn:active {
+  /** Scale down to 95% when clicked for tactile feedback */
   transform: scale(0.95);
   background: var(--exercise-primary);
   color: white;
 }
 
+/**
+ * Button & Action Styles
+ *
+ * Styles for submit buttons and other action controls.
+ */
+
 /* ========================================
-   ACTIONS & CONTROLS
+   SUBMIT BUTTON
    ======================================== */
 
 .exercise-submit-btn {
@@ -298,49 +461,69 @@ button.drag-option {
 }
 
 .exercise-submit-btn:active {
+  /** Scale down to 98% when clicked for tactile feedback */
   transform: scale(0.98);
 }
 
+/* Responsive Overrides - must be last */
+
+/**
+ * Responsive Design Styles
+ *
+ * Media queries for different screen sizes.
+ */
+
 /* ========================================
-   RESPONSIVE DESIGN
+   TABLET & SMALLER (max-width: 768px)
    ======================================== */
 
 @media (max-width: 768px) {
   .math-exercise-renderer {
+    /** Reduce padding by 25% on tablets */
     padding: calc(var(--exercise-padding) * 0.75);
   }
 
   .exercise-line {
+    /** Reduce gap between inline elements by 25% */
     gap: calc(var(--exercise-element-margin) * 0.75);
   }
 
   .drag-options {
+    /** Reduce gap between drag options */
     gap: var(--exercise-element-margin);
   }
 
   .numeric-keypad {
+    /** Reduce gap between keypad buttons */
     gap: var(--exercise-element-margin);
   }
 }
 
+/* ========================================
+   MOBILE (max-width: 480px)
+   ======================================== */
+
 @media (max-width: 480px) {
   .question-text {
+    /** Smaller question text on mobile */
     font-size: var(--exercise-font-size-large);
   }
 
   .inline-input {
+    /** Reduce input width by 20% on mobile */
     width: calc(var(--exercise-input-width) * 0.8);
   }
 
   .drag-option {
+    /** Reduce drag option width by 20% on mobile */
     min-width: calc(var(--exercise-button-width) * 0.8);
   }
 
   button.drag-option {
+    /** Reduce button drag option width by 20% on mobile */
     width: calc(var(--exercise-button-width) * 0.8);
   }
 }
-
 /* ============================================
    DND STYLES
    ============================================ */
@@ -441,8 +624,8 @@ button.drag-option {
   align-items: center;
   justify-content: center;
   border-radius: 4px;
-  min-width: 50px;
-  min-height: 40px;
+  /* min-width: 50px;
+  min-height: 40px; */
 }
 
 .inline-input {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mathscan/math-exercise-engine",
-  "version": "1.0.2",
+  "version": "1.0.3",
   "description": "A DSL parser and validator for math exercises - transforms text-based exercise definitions into structured AST and JSON",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -64,6 +64,9 @@
     }
   },
   "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
     "@types/node": "^20.11.0",
     "@types/react": "^18.2.0",
     "@types/react-dom": "^18.2.0",
@@ -71,6 +74,7 @@
     "@typescript-eslint/parser": "^6.19.0",
     "@vitest/coverage-v8": "^4.0.17",
     "eslint": "^8.56.0",
+    "jsdom": "^28.0.0",
     "prettier": "^3.2.4",
     "react": "^18.2.0",
     "react-dom": "^18.2.0",