add refresh_code and json_formatter to app gallery

docs/source/02-App-Gallery/e08_refresh_cache.py

@@ -0,0 +1,88 @@
+# -*- coding: utf-8 -*-
+
+"""
+Feature:
+
+No matter what user entered, always return a random value between 1 and 100.
+And this value is based on cache that won't change while user is typing.
+However, we want to provide a way to refresh the value. User can type "!~"
+and then hit ENTER to refresh the value. When user hit ENTER, it automatically
+removes the "!~" part and recover the original query.
+
+Difficulty: Hard
+
+Dependencies: NA
+
+Demo: https://asciinema.org/a/631197
+"""
+
+import random
+import dataclasses
+
+import zelfred.api as zf
+
+
+@dataclasses.dataclass
+class RefreshItem(zf.Item):
+    """
+    Represent an item that can refresh cache in the dropdown menu.
+    """
+
+    def enter_handler(self, ui: zf.UI):
+        """
+        Copy the content to clipboard.
+        """
+        cache.value = None
+
+    def post_enter_handler(self, ui: zf.UI):
+        """
+        After the user input action, we would like to repaint the dropdown menu
+        only to show the "Copied" item, and then wait for the next user input.
+        """
+        ui.line_editor.move_to_end()
+        ui.line_editor.press_backspace(self.variables["n_backspace"])
+
+
+class Cache:
+    def __init__(self):
+        self.value = None
+
+
+cache = Cache()
+
+
+def handler(query: str, ui: zf.UI):
+    """
+    The handler is the core of a Zelfred App. It's a user-defined function
+    that takes the entered query and the UI object as inputs and returns
+    a list of items to render.
+    """
+    # if query is for refresh value
+    if "!~" in query:
+        before_query, after_query = query.split("!~", 1)
+        return [
+            RefreshItem(
+                title="Refresh value",
+                subtitle=f"Hit {ui.render.ENTER} to refresh the value",
+                variables={"n_backspace": len(after_query) + 2},
+            )
+        ]
+    # otherwise, always return a random value, and cache it
+    else:
+        if cache.value is None:
+            cache.value = random.randint(1, 100)
+        return [
+            zf.Item(
+                title=f"Value {cache.value}",
+            )
+        ]
+
+
+if __name__ == "__main__":
+    # reset the debugger and enable it
+    zf.debugger.reset()
+    zf.debugger.enable()
+
+    # create the UI and run it
+    ui = zf.UI(handler=handler, capture_error=True)
+    ui.run()

docs/source/02-App-Gallery/e09_json_formatter.py

@@ -0,0 +1,63 @@
+# -*- coding: utf-8 -*-
+
+"""
+Feature:
+
+Copy JSON text to clipboard, then hit 'Enter' to dump the formatted JSON to
+``${HOME}/tmp/formatted.json`` and automatically open it.
+
+Difficulty: Easy
+
+Dependencies: NA
+
+Demo: https://asciinema.org/a/123456
+"""
+
+import json
+import dataclasses
+from pathlib import Path
+
+import pyperclip
+import zelfred.api as zf
+
+p = Path.home().joinpath("tmp", "formatted.json")
+p.parent.mkdir(exist_ok=True)
+
+
+@dataclasses.dataclass
+class JsonFormatterItem(zf.Item):
+    """
+    Represent a json formatter item in the dropdown menu.
+    """
+
+    def enter_handler(self, ui: zf.UI):
+        """
+        Read json from clipboard, format it, write to ~/tmp/formatted.json, then open it.
+        """
+        s = pyperclip.paste()
+        p.write_text(json.dumps(json.loads(s), indent=4))
+        zf.open_file(p)
+
+
+def handler(query: str, ui: zf.UI):
+    """
+    The handler is the core of a Zelfred App. It's a user-defined function
+    that takes the entered query and the UI object as inputs and returns
+    a list of items to render.
+    """
+    return [
+        JsonFormatterItem(
+            title=f"Hit 'Enter' to format your JSON",
+            subtitle="hint: copy your JSON to clipboard before you hit 'Enter'",
+        )
+    ]
+
+
+if __name__ == "__main__":
+    # reset the debugger and enable it
+    zf.debugger.reset()
+    zf.debugger.enable()
+
+    # create the UI and run it
+    ui = zf.UI(handler=handler, capture_error=True)
+    ui.run()

docs/source/02-App-Gallery/index.rst

@@ -130,3 +130,37 @@ User the user input to search the username, allow user to tap "Ctrl A" to copy t
     .. literalinclude:: ./e05_password_book.py
        :language: python
        :linenos:
+
+
+Refresh Cache
+------------------------------------------------------------------------------
+:bdg-warning:`Difficulty: Medium`
+
+No matter what user entered, always return a random value between 1 and 100. And this value is based on cache that won't change while user is typing. However, we want to provide a way to refresh the value. User can type "!~" and then hit "ENTER" to refresh the value. When user hit ENTER, it automatically removes the "!~" part and recover the original query.
+
+**Demo**
+
+.. image:: https://asciinema.org/a/631197.svg
+    :target: https://asciinema.org/a/631197
+
+.. dropdown:: **Source Code**
+
+    .. literalinclude:: ./e08_refresh_cache.py
+       :language: python
+       :linenos:
+
+
+JSON Formatter
+------------------------------------------------------------------------------
+:bdg-success:`Difficulty: Easy`
+
+Copy JSON text to clipboard, then hit 'Enter' to dump the formatted JSON to
+``${HOME}/tmp/formatted.json`` and automatically open it.
+
+**Demo**
+
+.. dropdown:: **Source Code**
+
+    .. literalinclude:: ./e09_json_formatter.py
+       :language: python
+       :linenos:

release-history.rst

@@ -15,6 +15,24 @@ x.y.z (Backlog)
 **Miscellaneous**
 
 
+0.3.1 (Backlog)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+**Features and Improvements**
+
+- Allow user to custom ``UIRender`` and use it in ``UI``.
+- Add ``open_url_or_print``, ``copy_or_print`` actions.
+
+**Minor Improvements**
+
+- Add the following sample app to app gallery:
+    - refresh_cache
+    - json_formatter
+
+**Bugfixes**
+
+**Miscellaneous**
+
+
 0.2.4 (2023-11-01)
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 **Bugfixes**