Demo: Option tooltips

README.md

@@ -66,7 +66,7 @@ Transpiles an Oniguruma pattern and returns a native JavaScript `RegExp`.
 function toRegExp(
   pattern: string,
   options?: Options
-): RegExp;
+): RegExp | EmulatedRegExp;
 ```
 
 #### Type `Options`
@@ -186,7 +186,7 @@ Supports all features of `default`, plus the following:
 
 *Default: `false`.*
 
-Prevents use of advanced emulation strategies that rely on returning a `RegExp` subclass, resulting in certain patterns not being emulatable.
+Disables advanced emulation strategies that rely on returning a `RegExp` subclass, resulting in certain patterns not being emulatable.
 
 ### `flags`
 
@@ -229,7 +229,7 @@ Higher limits have no effect on regexes that don't use recursion, so you should
 
 *Default: `'ES2024'`.*
 
-Sets the JavaScript language version for generated patterns and flags. Later targets allow faster processing, simpler generated source, and support for additional features.
+Sets the JavaScript language version for the generated pattern and flags. Later targets allow faster processing, simpler generated source, and support for additional features.
 
 <details>
   <summary>More details</summary>

demo/demo.css

@@ -14,7 +14,7 @@ body {
 main {
   background-color: rgba(255, 255, 255, 0.9);
   max-width: 65rem;
-  padding: 2.8vw 4.5vw;
+  padding: 4vh 4.5vw 3vw 4.5vw;
   margin: 0 auto;
   box-shadow: 0 0 0 10px #80c0ff;
   border-radius: 0 0 15px 15px;
@@ -55,12 +55,69 @@ summary {
 
 label {
   margin-right: 0.5em;
+  position: relative;
+  display: inline-block;
 }
 
 label img {
   vertical-align: middle;
 }
 
+label .tip {
+  visibility: hidden;
+  text-align: center;
+  padding: 4px 8px;
+  background-color: #c9e4ff;
+  border-radius: 6px;
+  position: absolute;
+  bottom: 130%;
+  left: 50%;
+  z-index: 1;
+}
+
+label:hover .tip {
+  visibility: visible;
+}
+
+label .tip:hover {
+  visibility: hidden;
+}
+
+label .tip::after {
+  content: " ";
+  position: absolute;
+  top: 100%;
+  left: 50%;
+  margin-left: -5px;
+  border-width: 5px;
+  border-style: solid;
+  border-color: #c9e4ff transparent transparent transparent;
+}
+
+label .tip-sm {
+  width: 130px;
+  margin-left: -65px;
+}
+
+label .tip-md {
+  width: 170px;
+  margin-left: -85px;
+}
+
+label .tip-lg {
+  width: 220px;
+  margin-left: -110px;
+}
+
+label .tip-xl {
+  width: 320px;
+  margin-left: -160px;
+}
+
+label .tip :is(code, kbd) {
+  background-color: #dceeff;
+}
+
 input[type='checkbox'] {
   width: 1.25em;
   height: 1.25em;

demo/index.html

@@ -23,14 +23,17 @@ <h2>Try it</h2>
       <label>
         <input type="checkbox" id="flag-i" onchange="setFlag('i', this.checked)">
         <kbd>i</kbd>
+        <span class="tip tip-sm"><code>ignoreCase</code></span>
       </label>
       <label>
         <input type="checkbox" id="flag-m" onchange="setFlag('m', this.checked)">
-        <kbd>m</kbd> <small>(JS flag <kbd>s</kbd>)</small>
+        <kbd>m</kbd>
+        <span class="tip tip-sm"><code>dotAll</code> <small>(JS flag <kbd>s</kbd>)</small></span>
       </label>
       <label>
         <input type="checkbox" id="flag-x" onchange="setFlag('x', this.checked)">
         <kbd>x</kbd>
+        <span class="tip tip-lg">Insignificant whitespace and comments</span>
       </label>
     </p>
     <p>
@@ -42,6 +45,7 @@ <h2>Try it</h2>
         </select>
         <code>target</code>
         <img src="https://upload.wikimedia.org/wikipedia/commons/9/99/Unofficial_JavaScript_logo_2.svg" width="15" height="15">
+        <span class="tip tip-lg">JS version for generated pattern and flags</span>
       </label>
       <label>
         <select id="option-accuracy" onchange="setOption('accuracy', this.value)">
@@ -50,6 +54,7 @@ <h2>Try it</h2>
           <option value="loose">loose</option>
         </select>
         <code>accuracy</code>
+        <span class="tip tip-lg">Level of emulation rigor</span>
       </label>
     </p>
     <details>
@@ -60,12 +65,14 @@ <h2>Try it</h2>
             <label>
               <input type="checkbox" id="option-global" onchange="setOption('global', this.checked)">
               <code>global</code>
+              <span class="tip tip-md">Add JS flag <kbd>g</kbd> to result</span>
             </label>
           </p>
           <p>
             <label>
               <input type="checkbox" id="option-hasIndices" onchange="setOption('hasIndices', this.checked)">
               <code>hasIndices</code>
+              <span class="tip tip-md">Add JS flag <kbd>d</kbd> to result</span>
             </label>
           </p>
         </div>
@@ -74,12 +81,14 @@ <h2>Try it</h2>
             <label>
               <input type="checkbox" id="option-avoidSubclass" onchange="setOption('avoidSubclass', this.checked)">
               <code>avoidSubclass</code>
+              <span class="tip tip-lg">Disables advanced emulation strategies that rely on a <code>RegExp</code> subclass</span>
             </label>
           </p>
           <p>
             <label>
               <input type="number" id="option-maxRecursionDepth" value="6" min="2" max="100" onchange="setOption('maxRecursionDepth', this.value)" onkeyup="setOption('maxRecursionDepth', this.value)">
               <code>maxRecursionDepth</code>
+              <span class="tip tip-lg">Use <code>2</code> to <code>100</code>, or <code>null</code> to disable recursion</span>
             </label>
           </p>
         </div>
@@ -88,20 +97,22 @@ <h2>Try it</h2>
             <label>
               <input type="checkbox" id="option-verbose" onchange="setOption('verbose', this.checked)">
               <code>verbose</code>
+              <span class="tip tip-lg">Disables optimizations that simplify the pattern</span>
             </label>
           </p>
           <p>
             <label>
               <input type="checkbox" id="option-tmGrammar" onchange="setOption('tmGrammar', this.checked)">
               <code>tmGrammar</code>
+              <span class="tip tip-xl">Leave disabled unless the regex will be used in a TextMate grammar processor that merges backrefs across <code>begin</code> and <code>end</code> patterns</span>
             </label>
           </p>
         </div>
       </section>
     </details>
     <pre id="output"></pre>
     <div id="info" class="hidden"><p>✅ A <code>RegExp</code> subclass instance with a custom execution strategy is returned for this pattern. It remains a native JavaScript regex and works the same as <code>RegExp</code> in all contexts.</p></div>
-    <p>The output shows the result of calling <code>toRegExp</code>. Oniguruma-To-ES functions <code>toDetails</code> and <code>toOnigurumaAst</code> can also be run from the console on this page, and you can pretty-print ASTs by passing them to <code>printAst</code>.</li>
+    <p>See <a href="https://github.com/slevithan/oniguruma-to-es#-options">Readme: Options</a> for more detailed explanations of each option. The output shows the result of calling <code>toRegExp</code>. Functions <code>toDetails</code> and <code>toOnigurumaAst</code> can be run from the console on this page, and you can pretty-print ASTs by passing them to <code>printAst</code>.</li>
   </main>
 
   <!-- Hack to make it work on GitHub Pages where `dist/` isn't checked in; use the latest release's copy -->

src/index.js

@@ -99,7 +99,7 @@ function toOnigurumaAst(pattern, options) {
 Transpiles an Oniguruma pattern and returns a native JavaScript `RegExp`.
 @param {string} pattern Oniguruma regex pattern.
 @param {Options} [options]
-@returns {RegExp}
+@returns {RegExp | EmulatedRegExp}
 */
 function toRegExp(pattern, options) {
   const result = toDetails(pattern, options);

src/options.js

@@ -29,8 +29,8 @@ function getOptions(options) {
   return {
     // Sets the level of emulation rigor/strictness.
     accuracy: 'default',
-    // Prevents use of advanced emulation strategies that rely on returning a `RegExp` subclass,
-    // resulting in certain patterns not being emulatable.
+    // Disables advanced emulation strategies that rely on returning a `RegExp` subclass, resulting
+    // in certain patterns not being emulatable.
     avoidSubclass: false,
     // Oniguruma flags; a string with `i`, `m`, and `x` in any order (all optional). Oniguruma's
     // `m` is equivalent to JavaScript's `s` (`dotAll`).
@@ -42,8 +42,8 @@ function getOptions(options) {
     // Specifies the recursion depth limit. Supported values are integers `2` to `100` and `null`.
     // If `null`, any use of recursion results in an error.
     maxRecursionDepth: 6,
-    // Sets the JavaScript language version for generated patterns and flags. Later targets allow
-    // faster processing, simpler generated source, and support for additional features.
+    // Sets the JavaScript language version for the generated pattern and flags. Later targets
+    // allow faster processing, simpler generated source, and support for additional features.
     target: 'ES2024',
     // Leave disabled unless the regex will be used in a TextMate grammar processor that merges
     // backreferences across `begin` and `end` patterns.

src/transform.js

@@ -590,10 +590,13 @@ function applySubclassStrategies(ast, accuracy) {
     alts[0].elements.length === 1 &&
     (firstEl.type === AstTypes.CapturingGroup || firstEl.type === AstTypes.Group) &&
     firstEl.alternatives.length === 1;
-  // First element within first group if the group doesn't contain top-level alternation, else just
-  // the first element of the pattern; a wrapper might be used to apply flags to the full pattern
-  const firstElIn = hasWrapperGroup ? firstEl.alternatives[0].elements[0] : firstEl;
   const singleAltIn = hasWrapperGroup ? firstEl.alternatives[0] : alts[0];
+  // First el within first group if the group doesn't contain top-level alternation, else just the
+  // first el of the pattern; ex: a flag group might enclose the full pattern
+  const firstElIn = hasWrapperGroup ? singleAltIn.elements[0] : firstEl;
+  if (!firstElIn) {
+    return null;
+  }
 
   // ## Strategy `line_or_search_start`: Support leading `(^|\G)` and similar
   if (