local web server to display and emulate layouts (#38)

Author: fabi1cazenave

MANIFEST.in

@@ -1,3 +1,4 @@
 include LICENSE
 include kalamine/data/*
 include kalamine/tpl/*
+include kalamine/www/*

Makefile

@@ -13,10 +13,11 @@ lint:
 	flake8 kalamine
 
 publish:
-	flake8 kalamine
+	# flake8 kalamine
 	rm -rf dist/*
 	python3 setup.py bdist_wheel
 	python3 setup.py sdist
+	twine check dist/*
 	twine upload dist/*
 
 publish-deps:

README.rst

@@ -80,6 +80,24 @@ You can also ask for a single target by specifying the file extension:
     kalamine layouts/ansi.toml --out q-ansi.xkb_custom
 
 
+Layout Emulation
+--------------------------------------------------------------------------------
+
+Your layout can be emulated in a browser — including dead keys and an AltGr layer, if any.
+
+
+.. code-block:: bash
+
+    $ kalamine layouts/prog.toml --watch
+    Server started: http://localhost:8080
+
+Open your browser, type in the input area, test your layout. Changes on your TOML file are not auto-detected yet, you’ll have to refresh the page manually.
+
+.. image:: watch.png
+
+Press Ctrl-C when you’re done, and kalamine will write all platform-specific files.
+
+
 Layout Installation
 --------------------------------------------------------------------------------
 
@@ -171,9 +189,7 @@ XKalamine
     xkalamine list us --all           # list all layouts for US English
     xkalamine list --all              # list all layouts, ordered by locale
 
-Note that updating xkb will delete every layouts installed using ``xkalamine install``.
-
-Using ``xkalamine`` with ``sudo`` currently supposes kalamine has been installed as root (hopefully in a pyenv). Which really sucks, and we’re working on a better solution.
+Note that updating XKB will delete all layouts installed using ``sudo xkalamine install``. Besides, using ``xkalamine`` with ``sudo`` supposes kalamine has been installed as root — hopefully in a pyenv:
 
 .. code-block:: bash
 
@@ -186,6 +202,15 @@ Using ``xkalamine`` with ``sudo`` currently supposes kalamine has been installed
    ln -s /path/to/pyenv/bin/kalamine
    ln -s /path/to/pyenv/bin/xkalamine
 
+We’re working on a solution to install keyboard layouts into ``~/.config/xkb``
+instead of ``/usr/share/X11/xkb``, but it will only work with Wayland.
+
+    If you want custom keymaps on your machine, switch to Wayland (and/or fix any remaining issues preventing you from doing so) instead of hoping this will ever work on X.
+
+    -- `Peter Hutterer`_
+
+.. _`Peter Hutterer`: https://who-t.blogspot.com/2020/09/no-user-specific-xkb-configuration-in-x.html
+
 XKB is a tricky piece of software. The following resources might be helpful if you want to dig in:
 
 * https://www.charvolant.org/doug/xkb/html/

kalamine/cli.py

@@ -6,6 +6,7 @@
 import click
 
 from .layout import KeyboardLayout
+from .server import keyboard_server
 
 
 def pretty_json(layout, path):
@@ -43,7 +44,7 @@ def out_path(ext=''):
         file.write(layout.xkb)
     print('... ' + xkb_path)
 
-    # Linux driver, user-space
+    # Linux driver, root
     xkb_custom_path = out_path('.xkb_custom')
     with open(xkb_custom_path, 'w', encoding='utf-8', newline='\n') as file:
         file.write(layout.xkb_patch)
@@ -58,16 +59,20 @@ def out_path(ext=''):
 @click.command()
 @click.argument('input', nargs=-1, type=click.Path(exists=True))
 @click.option('--version', '-v', is_flag=True)
+@click.option('--watch', '-w', is_flag=True)
 @click.option('--out',
               default='all',
               type=click.Path(),
               help='Keyboard driver(s) to generate.')
-def make(input, version, out):
+def make(input, version, watch, out):
     """ Convert toml/yaml descriptions into OS-specific keyboard layouts. """
 
     if version:
         print(f"kalamine { pkg_resources.require('kalamine')[0].version }")
 
+    if watch:
+        keyboard_server(input[0])
+
     for input_file in input:
         layout = KeyboardLayout(input_file)
 

kalamine/server.py

@@ -0,0 +1,97 @@
+#!/usr/bin/env python3
+from http.server import SimpleHTTPRequestHandler, HTTPServer
+import json
+import os
+
+from .layout import KeyboardLayout
+
+def keyboard_server(file_path):
+    kb_layout = KeyboardLayout(file_path)
+
+    host_name = 'localhost'
+    server_port = 8080
+
+    def main_page(layout):
+        return f"""
+            <!DOCTYPE html>
+            <html xmlns="http://www.w3.org/1999/xhtml">
+            <head>
+                <meta charset="utf-8" />
+                <title>Kalamine</title>
+                <link rel="stylesheet" type="text/css" href="style.css" />
+                <script src="x-keyboard.js" type="module"></script>
+                <script src="demo.js" type="text/javascript"></script>
+            </head>
+            <body>
+                <p>
+                    <a href="{layout.meta['url']}">{layout.meta['name']}</a>
+                    <br /> {layout.meta['locale']}/{layout.meta['variant']}
+                    <br /> {layout.meta['description']}
+                </p>
+                <input spellcheck="false" placeholder="" />
+                <x-keyboard src="/json"></x-keyboard>
+                <p style="text-align: right;">
+                    <select>
+                        <option value="iso">  ISO  </option>
+                        <option value="ansi"> ANSI </option>
+                        <option value="ol60"> ERGO </option>
+                        <option value="ol50"> 4×12 </option>
+                        <option value="ol40"> 3×12 </option>
+                    </select>
+                </p>
+                <p style="text-align: center;">
+                    <a href="/json">json</a>
+                    | <a href="/keylayout">keylayout</a>
+                    | <a href="/klc">klc</a>
+                    | <a href="/xkb">xkb</a>
+                    | <a href="/xkb_custom">xkb_custom</a>
+                </p>
+            </body>
+            </html>
+        """
+
+    class LayoutHandler(SimpleHTTPRequestHandler):
+        def __init__(self, *args, **kwargs):
+            dir_path = os.path.dirname(os.path.realpath(__file__))
+            www_path = os.path.join(dir_path, 'www')
+            super().__init__(*args, directory=www_path, **kwargs)
+
+        def do_GET(self):
+            self.send_response(200)
+
+            def send(page, content='text/plain', charset='utf-8'):
+                self.send_header('Content-type', f"{content}; charset={charset}")
+                self.end_headers()
+                self.wfile.write(bytes(page, charset))
+                # self.wfile.write(page.encode(charset))
+
+            # XXX always reloads the layout on the root page, never in sub pages
+            global kb_layout
+            if self.path == '/json':
+                send(json.dumps(kb_layout.json), content='application/json')
+            elif self.path == '/keylayout':
+                # send(kb_layout.keylayout, content='application/xml')
+                send(kb_layout.keylayout)
+            elif self.path == '/klc':
+                send(kb_layout.klc, charset='utf-16-le')
+            elif self.path == '/xkb':
+                send(kb_layout.xkb)
+            elif self.path == '/xkb_custom':
+                send(kb_layout.xkb_patch)
+            elif self.path == '/':
+                kb_layout = KeyboardLayout(file_path)  # refresh
+                send(main_page(kb_layout), content='text/html')
+            else:
+                return SimpleHTTPRequestHandler.do_GET(self)
+
+    webserver = HTTPServer((host_name, server_port), LayoutHandler)
+    print(f"Server started: http://{host_name}:{server_port}")
+    print('Hit Ctrl-C to stop.')
+
+    try:
+        webserver.serve_forever()
+    except KeyboardInterrupt:
+        pass
+
+    webserver.server_close()
+    print('Server stopped.')

kalamine/www/demo.js

@@ -0,0 +1,82 @@
+window.addEventListener('DOMContentLoaded', () => {
+  'use strict'; // eslint-disable-line
+
+  const keyboard = document.querySelector('x-keyboard');
+  const button   = document.querySelector('button');
+  const input    = document.querySelector('input');
+  const geometry = document.querySelector('select');
+
+  if (!keyboard.layout) {
+    console.warn('web components are not supported');
+    return; // the web component has not been loaded
+  }
+
+  fetch(keyboard.getAttribute('src'))
+    .then(response => response.json())
+    .then(data => {
+      const shape = data.geometry.replace('ergo', 'ol60').toLowerCase();
+      keyboard.setKeyboardLayout(data.keymap, data.deadkeys, shape);
+      geometry.value = shape;
+      button.hidden = false;
+      button.focus();
+    });
+
+  geometry.onchange = (event) => {
+    keyboard.geometry = event.target.value;
+  };
+
+  /**
+   * Keyboard highlighting & layout emulation
+   */
+
+  // required to work around a Chrome bug, see the `keyup` listener below
+  const pressedKeys = {};
+
+  // highlight keyboard keys and emulate the selected layout
+  input.onkeydown = (event) => {
+    pressedKeys[event.code] = true;
+    const value = keyboard.keyDown(event);
+    if (value) {
+      event.target.value += value;
+    } else if (event.code === 'Enter') { // clear text input on <Enter>
+      event.target.value = '';
+    } else if ((event.code === 'Tab') || (event.code === 'Escape')) {
+      setTimeout(close, 100);
+    } else {
+      return true; // don't intercept special keys or key shortcuts
+    }
+    return false; // event has been consumed, stop propagation
+  };
+  input.addEventListener('keyup', (event) => {
+    if (pressedKeys[event.code]) { // expected behavior
+      keyboard.keyUp(event);
+      delete pressedKeys[event.code];
+    } else {
+      /**
+       * We got a `keyup` event for a key that did not trigger any `keydown`
+       * event first: this is a known bug with "real" dead keys on Chrome.
+       * As a workaround, emulate a keydown + keyup. This introduces some lag,
+       * which can result in a typo (especially when the "real" dead key is used
+       * for an emulated dead key) -- but there's not much else we can do.
+       */
+      event.target.value += keyboard.keyDown(event);
+      setTimeout(() => keyboard.keyUp(event), 100);
+    }
+  });
+
+  /**
+   * When pressing a "real" dead key + key sequence, Firefox and Chrome will
+   * add the composed character directly to the text input (and nicely trigger
+   * an `insertCompositionText` or `insertText` input event, respectively).
+   * Not sure wether this is a bug or not -- but this is not the behavior we
+   * want for a keyboard layout emulation. The code below works around that.
+   */
+  input.addEventListener('input', (event) => {
+    if (event.inputType === 'insertCompositionText'
+      || event.inputType === 'insertText') {
+      event.target.value = event.target.value.slice(0, -event.data.length);
+    }
+  });
+
+  input.focus();
+});

kalamine/www/style.css

@@ -0,0 +1,20 @@
+body {
+  max-width: 64em;
+  margin: 0 auto;
+  font-family: sans-serif;
+}
+
+input {
+  width: 100%;
+  text-align: center;
+  font-size: 1.5em;
+  margin-bottom: 1em;
+}
+
+a { color: blue; }
+
+input, select { color-scheme: light dark; }
+@media (prefers-color-scheme: dark) {
+  html { background-color: #222; color: #ddd; }
+  a { color: #99f; }
+}