kash-shell 0.3.10__py3-none-any.whl → 0.3.11__py3-none-any.whl

kash/web_gen/simple_webpage.py

@@ -0,0 +1,52 @@
+from kash.model.items_model import Item
+from kash.utils.file_utils.file_formats_model import Format
+from kash.web_gen.template_render import render_web_template
+
+
+def simple_webpage_render(
+    item: Item,
+    page_template: str = "simple_webpage.html.jinja",
+    add_title_h1: bool = True,
+) -> str:
+    """
+    Generate a simple web page from a single item.
+    If `add_title_h1` is True, the title will be inserted as an h1 heading above the body.
+    """
+    return render_web_template(
+        template_filename=page_template,
+        data={
+            "title": item.title,
+            "add_title_h1": add_title_h1,
+            "content_html": item.body_as_html(),
+            "thumbnail_url": item.thumbnail_url,
+        },
+    )
+
+
+## Tests
+
+
+def test_render():
+    import os
+
+    from kash.model.items_model import ItemType
+
+    # Create a test item
+    item = Item(
+        type=ItemType.doc,
+        format=Format.html,
+        title="A Simple Web Page",
+        body="<p>This is a simple web page with <b>HTML content</b>.</p>",
+    )
+
+    # Generate HTML
+    html = simple_webpage_render(item)
+
+    os.makedirs("tmp", exist_ok=True)
+    with open("tmp/simple_webpage.html", "w") as f:
+        f.write(html)
+    print("Rendered simple webpage to tmp/simple_webpage.html")
+
+    # Basic validation
+    assert item.title and item.title in html
+    assert "<b>HTML content</b>" in html

kash/web_gen/tabbed_webpage.py

@@ -2,7 +2,7 @@ import os
 from dataclasses import asdict, dataclass
 
 from frontmatter_format import read_yaml_file, to_yaml_string, write_yaml_file
-from prettyfmt import sanitize_title
+from prettyfmt import abbrev_on_words, sanitize_title
 
 from kash.config.logger import get_logger
 from kash.exec.preconditions import has_thumbnail_url
@@ -12,7 +12,6 @@ from kash.model.paths_model import StorePath
 from kash.utils.common.type_utils import as_dataclass, not_none
 from kash.utils.errors import NoMatch
 from kash.utils.file_utils.file_formats_model import Format
-from kash.web_gen import base_templates_dir
 from kash.web_gen.template_render import render_web_template
 from kash.workspaces import current_ws
 from kash.workspaces.source_items import find_upstream_item
@@ -34,6 +33,7 @@ class TabbedWebpage:
     title: str
     tabs: list[TabInfo]
     show_tabs: bool = True
+    add_title_h1: bool = True
 
 
 def _fill_in_ids(tabs: list[TabInfo]):
@@ -42,7 +42,9 @@ def _fill_in_ids(tabs: list[TabInfo]):
             tab.id = f"tab_{i}"
 
 
-def webpage_config(items: list[Item], clean_headings: bool = False) -> Item:
+def tabbed_webpage_config(
+    items: list[Item], clean_headings: bool = False, add_title_h1: bool = True
+) -> Item:
     """
     Get an item with the config for a tabbed web page.
     """
@@ -58,11 +60,15 @@ def webpage_config(items: list[Item], clean_headings: bool = False) -> Item:
             log.warning("Item has no thumbnail URL: %s", item)
             return None
 
-    clean = clean_heading if clean_headings else sanitize_title
+    def clean_label(label: str) -> str:
+        if clean_headings:
+            return clean_heading(label)
+        else:
+            return abbrev_on_words(sanitize_title(label), max_len=40)
 
     tabs = [
         TabInfo(
-            label=clean(item.abbrev_title()),
+            label=clean_label(item.abbrev_title()),
             store_path=item.store_path,
             thumbnail_url=get_thumbnail_url(item),
         )
@@ -70,7 +76,9 @@ def webpage_config(items: list[Item], clean_headings: bool = False) -> Item:
     ]
     _fill_in_ids(tabs)
     title = summary_heading([item.abbrev_title() for item in items])
-    config = TabbedWebpage(title=title, tabs=tabs, show_tabs=len(tabs) > 1)
+    config = TabbedWebpage(
+        title=title, tabs=tabs, show_tabs=len(tabs) > 1, add_title_h1=add_title_h1
+    )
 
     config_item = Item(
         title=f"{title} (config)",
@@ -91,7 +99,9 @@ def _load_tab_content(config: TabbedWebpage):
         tab.content_html = html
 
 
-def webpage_generate(config_item: Item) -> str:
+def tabbed_webpage_generate(
+    config_item: Item, page_template: str = "base_webpage.html.jinja", add_title_h1: bool = True
+) -> str:
     """
     Generate a web page using the supplied config.
     """
@@ -101,14 +111,15 @@ def webpage_generate(config_item: Item) -> str:
     _load_tab_content(tabbed_webpage)
 
     content = render_web_template(
-        base_templates_dir, "tabbed_webpage.html.jinja", asdict(tabbed_webpage)
+        template_filename="tabbed_webpage.html.jinja",
+        data=asdict(tabbed_webpage),
     )
 
     return render_web_template(
-        base_templates_dir,
-        "base_webpage.html.jinja",
-        {
+        page_template,
+        data={
             "title": tabbed_webpage.title,
+            "add_title_h1": add_title_h1,
             "content": content,
         },
     )
@@ -138,11 +149,7 @@ def test_render():
     new_config = as_dataclass(read_yaml_file("tmp/webpage_config.yaml"), TabbedWebpage)
     assert new_config == config
 
-    html = render_web_template(
-        base_templates_dir,
-        "tabbed_webpage.html.jinja",
-        asdict(config),
-    )
+    html = render_web_template(template_filename="tabbed_webpage.html.jinja", data=asdict(config))
     with open("tmp/webpage.html", "w") as f:
         f.write(html)
     print("Rendered tabbed webpage to tmp/webpage.html")

kash/web_gen/template_render.py

@@ -1,12 +1,45 @@
+from collections.abc import Iterator
+from contextlib import contextmanager
+from contextvars import ContextVar
 from pathlib import Path
 
 from jinja2 import Environment, FileSystemLoader
 
 from kash.config import colors
 
+_base_templates_dir = Path(__file__).parent / "templates"
+"""Common base web page templates."""
+
+
+_additional_template_dirs: ContextVar[list[Path] | None] = ContextVar(
+    "_additional_template_dirs", default=None
+)
+
+
+def get_template_dirs(*dirs: Path) -> list[Path]:
+    """
+    Returns template directories currently in context along with any
+    additional template directories.
+    """
+    additional = _additional_template_dirs.get() or []
+    return list(dirs) + [*additional, _base_templates_dir]
+
+
+@contextmanager
+def additional_template_dirs(*dirs: Path) -> Iterator[None]:
+    """
+    Context manager for temporarily adding template directories to the search path.
+    """
+    original = _additional_template_dirs.get()
+    current = [] if not original else original.copy()
+    token = _additional_template_dirs.set(current + list(dirs))
+    try:
+        yield
+    finally:
+        _additional_template_dirs.reset(token)
+
 
 def render_web_template(
-    templates_dir: Path,
     template_filename: str,
     data: dict,
     autoescape: bool = True,
@@ -14,11 +47,13 @@ def render_web_template(
 ) -> str:
     """
     Render a Jinja2 template file with the given data, returning an HTML string.
+    Uses template directories from the base directory and any added via context manager.
     """
     if css_overrides is None:
         css_overrides = {}
 
-    env = Environment(loader=FileSystemLoader(templates_dir), autoescape=autoescape)
+    search_paths = get_template_dirs()
+    env = Environment(loader=FileSystemLoader(search_paths), autoescape=autoescape)
 
     # Load and render the template.
     template = env.get_template(template_filename)

kash/web_gen/templates/base_styles.css.jinja

@@ -1,4 +1,5 @@
 :root {
+  {% block root_variables %}
   font-size: 16px;
   /* Adding Hack Nerd Font to all fonts for icon support, if it is installed. */
   --font-sans: "Source Sans 3 Variable", sans-serif, "Hack Nerd Font";
@@ -16,14 +17,17 @@
 
   --console-char-width: 88;
   --console-width: calc(var(--console-char-width) + 2rem);
+  {% endblock root_variables %}
 }
 
 {{ color_defs|safe }}
 
+{% block selection_styles %}
 ::selection {
   background-color: var(--color-selection);
   color: inherit;
 }
+{% endblock selection_styles %}
 
 {# TODO: Fix PDF issues and re-enable for prettier emoji. #}
 {# @font-face {
@@ -39,6 +43,7 @@
     U+1F900-1F9FF;  /* Supplemental Symbols and Pictographs */ 
 } #}
 
+{% block scrollbar_styles %}
 /* Scrollbar coloring. */
 /* For Webkit browsers (Chrome, Safari) */
 ::-webkit-scrollbar {
@@ -60,7 +65,9 @@
   scrollbar-width: thin;
   scrollbar-color: var(--color-scrollbar) var(--color-bg);
 }
+{% endblock scrollbar_styles %}
 
+{% block body_styles %}
 body {
   font-family: var(--font-serif);
   color: var(--color-text);
@@ -70,7 +77,9 @@ body {
   background-color: var(--color-bg);
   overflow-wrap: break-word;  /* Don't let long words/URLs break layout. */
 }
+{% endblock body_styles %}
 
+{% block typography %}
 p {
   margin-bottom: 1rem;
 }
@@ -120,37 +129,6 @@ h4 {
   margin-bottom: 0.7rem;
 }
 
-/* Long text stylings, for nicely formatting blog post length or longer texts. */
-
-.long-text h1 {
-  font-family: var(--font-serif);
-  font-weight: 400;
-}
-
-.long-text h2 {
-  font-family: var(--font-serif);
-  font-weight: 400;
-  font-style: italic;
-}
-
-.long-text h3 {
-  font-family: var(--font-sans);
-  font-weight: var(--font-weight-sans-bold);
-  text-transform: uppercase;
-  letter-spacing: 0.02em;
-}
-
-.long-text h4 {
-  font-family: var(--font-serif);
-  font-weight: 700;
-}
-
-.subtitle {
-  font-family: var(--font-serif);
-  font-style: italic;
-  font-size: 1rem;
-}
-
 ul {
   list-style-type: none;
   margin-left: 2rem;
@@ -207,7 +185,42 @@ pre {
   letter-spacing: -0.025em;
   {# overflow-x: auto; #}
 }
+{% endblock typography %}
+
+{% block long_text_styles %}
+/* Long text stylings, for nicely formatting blog post length or longer texts. */
+
+.long-text h1 {
+  font-family: var(--font-serif);
+  font-weight: 400;
+}
+
+.long-text h2 {
+  font-family: var(--font-serif);
+  font-weight: 400;
+  font-style: italic;
+}
+
+.long-text h3 {
+  font-family: var(--font-sans);
+  font-weight: var(--font-weight-sans-bold);
+  text-transform: uppercase;
+  letter-spacing: 0.02em;
+}
+
+.long-text h4 {
+  font-family: var(--font-serif);
+  font-weight: 700;
+}
 
+.subtitle {
+  font-family: var(--font-serif);
+  font-style: italic;
+  font-size: 1rem;
+}
+{% endblock long_text_styles %}
+
+{% block table_styles %}
 table {
   font-family: var(--font-sans);
   font-size: var(--font-size-small);
@@ -239,16 +252,6 @@ tbody tr:nth-child(even) {
   background-color: var(--color-bg-alt-solid); 
 }
 
-nav {
-  display: flex;
-  flex-wrap: wrap;
-  /* Allow wrapping */
-  justify-content: center;
-  /* Center the content */
-  gap: 1rem;
-  /* Add some space between the buttons */
-}
-
 /* Container for wide tables to allow tables to break out of parent width. */
 .table-container {
   {# max-width: calc(100vw - 6rem); #}
@@ -258,26 +261,24 @@ nav {
   box-sizing: border-box;
   margin-bottom: 1rem;
   background-color: var(--color-bg-solid);
-
 }
+{% endblock table_styles %}
 
-/* Bleed wide on larger screens. */
-/* TODO: Don't make so wide if table itself isn't large? */
-@media (min-width: 768px) {
-  table {
-    width: calc(100vw - 6rem);
-  }
-  .table-container {
-    width: calc(100vw - 6rem);
-  }
+{% block nav_styles %}
+nav {
+  display: flex;
+  flex-wrap: wrap;
+  /* Allow wrapping */
+  justify-content: center;
+  /* Center the content */
+  gap: 1rem;
+  /* Add some space between the buttons */
 }
+{% endblock nav_styles %}
 
-@media (max-width: 768px) {
-  table {
-    font-size: var(--font-size-smaller);
-  }
-}
 
+
+{% block footnote_styles %}
 /* Footnotes. */
 sup {
   font-size: 80%;
@@ -295,4 +296,23 @@ sup {
   color: var(--color-primary-light);
   text-decoration: none;
 }
+{% endblock footnote_styles %}
+
+{% block responsive_styles %}
+/* Bleed wide on larger screens. */
+/* TODO: Don't make so wide if table itself isn't large? */
+@media (min-width: 768px) {
+  table {
+    width: calc(100vw - 6rem);
+  }
+  .table-container {
+    width: calc(100vw - 6rem);
+  }
+}
 
+@media (max-width: 768px) {
+  table {
+    font-size: var(--font-size-smaller);
+  }
+}
+{% endblock responsive_styles %}

kash/web_gen/templates/base_webpage.html.jinja

@@ -2,10 +2,14 @@
 <html lang="en">
 
 <head>
+  {% block meta %}
   <meta charset="UTF-8" />
   <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-  <title>{{ title }}</title>
+  {% endblock meta %}
 
+  {% block title %}<title>{{ title }}</title>{% endblock title %}
+
+  {% block head_basic %}
   <link rel="preconnect" href="https://fonts.googleapis.com" />
   <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
   <link rel="preconnect" href="https://cdn.jsdelivr.net" crossorigin />
@@ -26,12 +30,12 @@
 
   <link href="https://cdn.jsdelivr.net/npm/tailwindcss@2.2.19/dist/tailwind.min.css" rel="stylesheet" />
   <script src="https://cdn.jsdelivr.net/npm/feather-icons/dist/feather.min.js" defer></script>
+  {% endblock head_basic %}
 
-  {% if extra_head %}
-  {{ extra_head|safe }}
-  {% endif %}
+  {% block head_extra %}{% endblock head_extra %}
 
   <style>
+    {% block font_faces %}
     /* https://fontsource.org/fonts/pt-serif/cdn */
     /* pt-serif-latin-400-normal */
     @font-face {
@@ -88,84 +92,98 @@
       src: url(https://cdn.jsdelivr.net/fontsource/fonts/source-sans-3:vf@latest/latin-wght-italic.woff2) format('woff2-variations');
       unicode-range: U+0000-00FF,U+0131,U+0152-0153,U+02BB-02BC,U+02C6,U+02DA,U+02DC,U+0304,U+0308,U+0329,U+2000-206F,U+20AC,U+2122,U+2191,U+2193,U+2212,U+2215,U+FEFF,U+FFFD;
     }
-
     {# Other decent sans serif options: Work Sans Variable, Nunito Sans Variable #}
+    {% endblock font_faces %}
 
+    {% block base_styles %}
     {% include "base_styles.css.jinja" %}
+    {% endblock base_styles %}
+    
+    {% block content_styles %}
     {% include "content_styles.css.jinja" %}
-
-    {% if extra_css %}
-    {{ extra_css|safe }}
-    {% endif %}
+    {% endblock content_styles %}
+    
+    {% block custom_styles %}{% endblock custom_styles %}
   </style>
-
 </head>
 
 <body>
-{{ content|safe }}
-
-<script>
-  document.addEventListener('DOMContentLoaded', () => {
-    // Send messages to the parent window, in case we are in a viewport where that matters
-    // (e.g. an iframe tooltip).
-    // Request a resize of the parent viewport. This iframe size message format isn't
-    // standardized by ResizeObserver, but is common. It is supported by Kerm.
-    const content = document.body;
-    console.log("Suggesting resize to parent:", content.offsetWidth, content.offsetHeight);
-
-    window.parent.postMessage({
-      type: 'resize',
-      width: Math.max(content.offsetWidth, 600),
-      height: Math.max(content.offsetHeight, 100)
-    }, '*');
-
-    // Wrap tables within the main content area for horizontal scrolling.
-    const containers = [];
-    document.querySelectorAll('.long-text').forEach(el => {
-      const pane = el.querySelector('.tab-pane');
-      containers.push(pane || el);
-    });
-    containers.forEach(container => {
-      // Grab all tables, then only wrap the ones whose parent is this container.
-      container.querySelectorAll('table').forEach(table => {
-        if (table.parentElement !== container) {
-          return; // Only direct children.
-        }
-        if (table.parentNode.classList.contains('table-container')) {
-          return; // Already wrapped.
-        }
-        const wrapper = document.createElement('div');
-        wrapper.className = 'table-container';
-        container.insertBefore(wrapper, table);
-        wrapper.appendChild(table);
-      });
-    });
+  {% block body_header %}{% endblock body_header %}
+  
+  {% block main_content %}
+  {{ content|safe }}
+  {% endblock main_content %}
+  
+  {% block body_footer %}{% endblock body_footer %}
+
+  {% block scripts %}
+  <script>
+    document.addEventListener('DOMContentLoaded', () => {
+      // Send messages to the parent window, in case we are in a viewport where that matters
+      // (e.g. an iframe tooltip).
+      // Request a resize of the parent viewport. This iframe size message format isn't
+      // standardized by ResizeObserver, but is common. It is supported by Kerm.
+      const content = document.body;
+      console.log("Suggesting resize to parent:", content.offsetWidth, content.offsetHeight);
 
-  });
+      window.parent.postMessage({
+        type: 'resize',
+        width: Math.max(content.offsetWidth, 600),
+        height: Math.max(content.offsetHeight, 100)
+      }, '*');
 
-  // Double-click to expand (e.g. expand tooltip to popover).
-  document.addEventListener('dblclick', () => {
-    console.log("Sending expand message to parent");
-    window.parent.postMessage({
-      type: 'expand'
-    }, '*');
-  });
+      // Wrap tables within the main content area for horizontal scrolling.
+      const containers = [];
+      document.querySelectorAll('.long-text').forEach(el => {
+        const pane = el.querySelector('.tab-pane');
+        containers.push(pane || el);
+      });
+      containers.forEach(container => {
+        // Find all tables within the container.
+        const tables = Array.from(container.querySelectorAll('table'));
+        tables.forEach(table => {
+          // Skip tables already in table-container divs
+          if (table.parentNode.classList.contains('table-container')) {
+            return;
+          }
+          try {
+            // Create the wrapper.
+            const wrapper = document.createElement('div');
+            wrapper.className = 'table-container';
+            // Get the parent and insert the wrapper where the table is, then move the table into the wrapper.
+            const parent = table.parentNode;
+            parent.insertBefore(wrapper, table);
+            wrapper.appendChild(table);
+          } catch (e) {
+            console.error("Error wrapping table:", e);
+          }
+        });
+      });
+    });
 
-  // Escape to close tooltip or popover.
-  document.addEventListener('keydown', (event) => {
-    if (event.key === 'Escape') {
-      console.log("Sending close message to parent");
+    // Double-click to expand (e.g. expand tooltip to popover).
+    document.addEventListener('dblclick', () => {
+      console.log("Sending expand message to parent");
       window.parent.postMessage({
-        type: 'close'
+        type: 'expand'
       }, '*');
-    }
-  });
+    });
 
-  {% if extra_footer_js %}
-  {{ extra_footer_js|safe }}
-  {% endif %}
-</script>
+    // Escape to close tooltip or popover.
+    document.addEventListener('keydown', (event) => {
+      if (event.key === 'Escape') {
+        console.log("Sending close message to parent");
+        window.parent.postMessage({
+          type: 'close'
+        }, '*');
+      }
+    });
 
+    {% block scripts_extra %}{% endblock scripts_extra %}
+  </script>
+  {% endblock scripts %}
+  
+  {% block analytics %}{% endblock analytics %}
 </body>
 
 </html>