picata 0.0.1__py3-none-any.whl

LICENSE.md

@@ -0,0 +1,24 @@
+# The MIT License (MIT)
+
+Copyright © `2024` `Ada Wright <ada@hpk.io>`
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the “Software”), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

README.md

@@ -0,0 +1,59 @@
+# Ada's website
+
+Wherein I set up a little website, and learn a bunch of stuff as I go.
+
+## What it's made of
+
+### Inside the box
+
+- [Wagtail](https://wagtail.org) (on [Django](https://www.djangoproject.com)) is the web framework
+<!-- - [Tailwind CSS](https://tailwindcss.com) for styling -->
+
+### Holding things together
+
+- [UV](https://github.com/astral-sh/uv) for all Python project management
+- [Just](https://just.systems) as a command runner
+- [OpenTofu](https://opentofu.org) for DevOps
+- [Postgres](https://www.postgresql.org) for the database
+- [Docker](https://www.docker.com) for local development
+
+## Quickstart
+
+### Requirements
+
+- On a Mac:
+
+```shell
+brew install colima docker
+```
+
+### Run a development server
+
+```shell
+just tofu workspace select dev
+just tofu apply
+```
+
+This will spin up a box on DigitalOcean using the settings defined in
+[infra/variables.tf](infra/variables.tf), and create a DNS A record at
+(workspace).for.(tld), (i.e. dev.for.hpk.io) pointing to the box. The variables
+`do_token` and `ssh_fingerprint` should be defined in
+[infra/secrets.tfvars](infra/secrets.tfvars). Workspace-specific variables are
+defined in infra/envs/(workspace).tfvars; e.g.
+[infra/envs/dev.tfvars](infra/envs/dev.tfvars) defines the 'tags' list for the
+box as `[development]` and sets `cloud_init_config` to point to the
+[cloud-init](https://cloud-init.io) script
+[config/cloud-init-dev.yml](config/cloud-init-dev.yml).
+
+The development cloud-init script will:
+
+- Install the system packages [`just`](https://just.systems), [`zsh`](https://www.zsh.org),
+  [`gunicorn`](https://gunicorn.org), and `tree`
+- Create a 'wagtail' user, with UID 1500
+- Create the 'ada' user, and:
+  - install their SSH public keys,
+  - install their dotfiles,
+  - add them to the 'sudo' and 'wagtail' groups
+- Install [Node](http://nodejs.org) on the system, from the `TF_VAR_NODE_VERSION`
+  defined in [.env](.env)
+- Checkout this repository into `/app`, setting the owner and group to 'wagtail'.

components/HelloWorld.tsx

@@ -0,0 +1,11 @@
+import React from "react";
+
+type Props = {
+  name: string;
+};
+
+const HelloWorld: React.FC<Props> = ({ name }) => {
+  return <h1>Hello, {name}!</h1>;
+};
+
+export default HelloWorld;

entrypoint.tsx

@@ -0,0 +1,268 @@
+import "./styles.sass";
+
+const THEMES = {
+  light: "fl",
+  dark: "ad",
+};
+
+// Set listeners on data-set-theme attributes to change the theme
+import { themeChange } from "theme-change";
+themeChange();
+
+//
+// Theme "reset to system defaults", and "light"/"dark" data-theme-mode logic
+//
+function initializeThemeReset() {
+  const themeReset = document.querySelector<HTMLSpanElement>("#theme-reset");
+  const themeButtons = document.querySelectorAll<HTMLButtonElement>("[data-set-theme]");
+
+  const updateThemeMode = () => {
+    const theme = document.documentElement.getAttribute("data-theme");
+    if (theme === THEMES.dark || theme === THEMES.light) {
+      document.documentElement.setAttribute(
+        "data-theme-mode",
+        theme === THEMES.dark ? "dark" : "light",
+      );
+    } else {
+      const prefersDark = window.matchMedia("(prefers-color-scheme: dark)").matches;
+      document.documentElement.setAttribute("data-theme-mode", prefersDark ? "dark" : "light");
+    }
+  };
+
+  const updateThemeResetButtonVisibility = () => {
+    if (themeReset) {
+      const isThemeSet = document.documentElement.hasAttribute("data-theme");
+      if (isThemeSet) {
+        themeReset.classList.remove("hidden", "pointer-events-none");
+      } else {
+        themeReset.classList.add("hidden", "pointer-events-none");
+      }
+    }
+  };
+
+  // Initialize on page load
+  updateThemeMode();
+  updateThemeResetButtonVisibility();
+
+  // Add a listener for system preference changes
+  const prefersDarkQuery = window.matchMedia("(prefers-color-scheme: dark)");
+  prefersDarkQuery.addEventListener("change", () => {
+    if (!document.documentElement.getAttribute("data-theme")) {
+      updateThemeMode();
+    }
+  });
+
+  // Monitor changes to the data-theme attribute
+  const themeChangeObserver = new MutationObserver(() => {
+    updateThemeMode();
+    updateThemeResetButtonVisibility();
+  });
+  themeChangeObserver.observe(document.documentElement, {
+    attributes: true,
+    attributeFilter: ["data-theme"],
+  });
+
+  // Add click listener for the reset button
+  if (themeReset) {
+    themeReset.addEventListener("click", () => {
+      document.documentElement.removeAttribute("data-theme");
+      localStorage.removeItem("theme");
+
+      themeButtons.forEach((button) => {
+        button.classList.remove("btn-active");
+      });
+
+      updateThemeMode();
+      updateThemeResetButtonVisibility();
+    });
+  } else {
+    console.error("Could not find #theme-reset element.");
+  }
+
+  // Add listeners to theme buttons to toggle "btn-active" class
+  themeButtons.forEach((button) => {
+    button.addEventListener("click", () => {
+      const newTheme = button.getAttribute("data-set-theme");
+      if (newTheme) {
+        document.documentElement.setAttribute("data-theme", newTheme);
+        localStorage.setItem("theme", newTheme);
+      }
+
+      themeButtons.forEach((btn) => btn.classList.remove("btn-active"));
+      button.classList.add("btn-active");
+
+      updateThemeMode();
+    });
+  });
+}
+
+//
+// Search field toggling logic
+//
+function initializeSearchFieldToggle() {
+  const searchToggleButton = document.getElementById("search-toggle") as HTMLButtonElement | null;
+  const searchField = document.getElementById("search-field") as HTMLElement | null;
+
+  if (!searchToggleButton || !searchField) {
+    console.error("Search toggle or search field elements not found.");
+    return;
+  }
+
+  searchToggleButton.addEventListener("click", () => {
+    const isVisible = searchField.classList.toggle("search-visible");
+    searchField.classList.toggle("search-hidden", !isVisible);
+    searchField.setAttribute("tabindex", isVisible ? "0" : "-1");
+    searchToggleButton.classList.toggle("!rounded-r-none", isVisible);
+    searchToggleButton.classList.toggle("!rounded-r-full", !isVisible);
+    searchToggleButton.setAttribute("aria-expanded", isVisible.toString());
+    if (isVisible) {
+      searchField.focus();
+    }
+  });
+}
+
+//
+// Apply shadows to the right of code blocks when they overflow their container
+//
+function initializeCodeBlockOverflowWatchers(): void {
+  const pygmentsDivs: NodeListOf<HTMLDivElement> = document.querySelectorAll(".pygments");
+
+  const applyOverflowClass = (div: HTMLDivElement) => {
+    const pre = div.querySelector("pre");
+    if (!pre) return;
+
+    if (pre.scrollWidth > pre.clientWidth) {
+      div.classList.add("shadow-fade-right");
+    } else {
+      div.classList.remove("shadow-fade-right");
+    }
+  };
+
+  // Apply initial shadows
+  pygmentsDivs.forEach(applyOverflowClass);
+
+  // Add resize listener to recheck on window resize
+  window.addEventListener("resize", () => {
+    pygmentsDivs.forEach(applyOverflowClass);
+  });
+}
+
+//
+// Create the nested list of internal page links for a 'Page Contents' container
+//
+function renderPageContents(): void {
+  const tocContainer = document.querySelector("main nav .toc");
+  if (!tocContainer) return;
+
+  // Create the header for the navigation
+  const tocHeader = document.createElement("h2");
+  tocHeader.textContent = "In this page";
+  tocContainer.appendChild(tocHeader);
+
+  // Create the root list
+  const tocList = document.createElement("ul");
+  tocContainer.appendChild(tocList);
+
+  // Stack to track the current list level
+  const listStack: HTMLUListElement[] = [tocList];
+  let currentLevel = 1;
+
+  // Find all anchor-linked headings
+  const headings = document.querySelectorAll<HTMLElement>(
+    "h1[id], h2[id], h3[id], h4[id], h5[id], h6[id]",
+  );
+  headings.forEach((heading) => {
+    const headingLevel = parseInt(heading.tagName.substring(1)); // Extract the heading level (e.g., "1" for "H1")
+
+    // Adjust the stack to match the heading level
+    while (headingLevel > currentLevel) {
+      // Create intermediate sub-lists for skipped levels
+      const newList = document.createElement("ul");
+      const lastItem = listStack[listStack.length - 1].lastElementChild;
+
+      if (lastItem) {
+        lastItem.appendChild(newList);
+        listStack.push(newList);
+      } else {
+        // If no previous item exists, append directly to the current list
+        listStack[listStack.length - 1].appendChild(newList);
+        listStack.push(newList);
+      }
+      currentLevel++;
+    }
+
+    while (headingLevel < currentLevel) {
+      // Pop back to the parent list
+      listStack.pop();
+      currentLevel--;
+    }
+
+    // Add the heading to the current list
+    const listItem = document.createElement("li");
+    const link = document.createElement("a");
+
+    // Get heading text without pilcrow
+    link.href = `#${heading.id}`;
+    link.textContent = heading.textContent?.replace("¶", "").trim() || "Untitled"; // Remove pilcrow
+    listItem.appendChild(link);
+
+    listStack[listStack.length - 1].appendChild(listItem);
+  });
+}
+
+// function enableStickyTOC(): void {
+//   const tocContainer = document.querySelector<HTMLElement>(".toc > div");
+//   if (!tocContainer) return;
+
+//   const parentContainer = tocContainer.parentElement;
+//   if (!parentContainer) return;
+
+//   const offsetTop = 16; // Equivalent to Tailwind's `top-4`
+//   const marginRight = 16; // Equivalent to Tailwind's `-mr-4`
+
+//   const initialTop = parentContainer.getBoundingClientRect().top + window.scrollY;
+//   const parentStyles = getComputedStyle(parentContainer);
+
+//   window.addEventListener("scroll", () => {
+//     const currentScroll = window.scrollY;
+//     const stickyStart = initialTop - offsetTop;
+
+//     if (currentScroll >= stickyStart) {
+//       tocContainer.classList.add("is-fixed");
+
+//       tocContainer.style.position = "fixed";
+//       tocContainer.style.top = `${offsetTop}px`;
+//       tocContainer.style.maxHeight = `calc(100vh - ${offsetTop}px)`;
+//       tocContainer.style.overflowY = "auto";
+
+//       // Dynamically calculate width and right offset
+//       const parentWidth = parentContainer.getBoundingClientRect().width;
+//       tocContainer.style.width = `${parentWidth}px`;
+//       tocContainer.style.padding = parentStyles.padding; // Preserve padding
+//       tocContainer.style.right = `${marginRight}px`; // Apply negative right margin
+//     } else {
+//       tocContainer.classList.remove("is-fixed");
+
+//       tocContainer.style.position = "relative";
+//       tocContainer.style.top = "initial";
+//       tocContainer.style.maxHeight = "initial";
+//       tocContainer.style.overflowY = "initial";
+
+//       // Reset dynamically applied styles
+//       tocContainer.style.width = "initial";
+//       tocContainer.style.padding = "initial";
+//       tocContainer.style.right = "initial"; // Reset right offset
+//     }
+//   });
+// }
+
+//
+// Main DOMContentLoaded Listener
+//
+document.addEventListener("DOMContentLoaded", () => {
+  initializeThemeReset();
+  initializeSearchFieldToggle();
+  initializeCodeBlockOverflowWatchers();
+  renderPageContents();
+  // enableStickyTOC();
+});

manage.py

@@ -0,0 +1,15 @@
+#!/usr/bin/env python
+"""Entry-point for Django management commands."""
+
+from os import environ
+from sys import argv
+
+if __name__ == "__main__":
+    environ.setdefault("DJANGO_SETTINGS_MODULE", "hpk.settings.dev")
+
+    if len(argv) >= 2:  # noqa: PLR2004
+        environ.setdefault("DJANGO_MANAGEMENT_COMMAND", argv[1])
+
+    from django.core.management import execute_from_command_line
+
+    execute_from_command_line(argv)

picata/__init__.py

@@ -0,0 +1 @@
+"""Main "umbrella" package for custom code running hpk.io."""

picata/apps.py

@@ -0,0 +1,33 @@
+"""Application configuration for the hpk Django app."""
+
+from django.apps import AppConfig
+
+
+class Config(AppConfig):
+    """Configuration class for the hpk Django application."""
+
+    default_auto_field = "django.db.models.BigAutoField"
+    name = "hpk"
+
+    def ready(self) -> None:
+        """Configure Wagtail admin with custom models, and register document transformers."""
+        #
+        # Register the 'custom article type' model with the Wagtail admin
+        from wagtail_modeladmin.options import modeladmin_register
+
+        from hpk.models import ArticleTypeAdmin
+
+        modeladmin_register(ArticleTypeAdmin)
+
+        # Add document transformers to the HTMLProcessingMiddleware
+        from hpk.middleware import HTMLProcessingMiddleware
+        from hpk.transformers import AnchorInserter, add_heading_ids
+
+        ## Add ids to all headings missing them within html > body > main
+        HTMLProcessingMiddleware.add_transformer(add_heading_ids)
+
+        ## Add anchored pillcrows to headings in designated pages
+        anchor_inserter = AnchorInserter(
+            root="//main/article", targets=".//h1 | .//h2 | .//h3 | .//h4 | .//h5 | .//h6"
+        )
+        HTMLProcessingMiddleware.add_transformer(anchor_inserter)

picata/blocks.py

@@ -0,0 +1,175 @@
+"""Wagtail "blocks"."""
+
+import pygments
+from django.forms import CharField
+from django.utils.html import format_html
+from hpk.typing.wagtail import BlockRenderContext, BlockRenderValue
+from hpk.validators import HREFValidator
+from pygments import formatters, lexers
+from pygments.util import ClassNotFound
+from wagtail.blocks import (
+    CharBlock,
+    ChoiceBlock,
+    IntegerBlock,
+    ListBlock,
+    RichTextBlock,
+    StreamBlock,
+    StructBlock,
+    TextBlock,
+    URLBlock,
+)
+from wagtail.images.blocks import ImageChooserBlock
+
+
+class HREFField(CharField):
+    """Custom field for href attributes (i.e. URLs but also schemes like 'mailto:')."""
+
+    def __init__(self, *args, **kwargs) -> None:  # noqa: ANN002, ANN003
+        """Initialise a CharField with `HREFValidator` as the only validator."""
+        kwargs["validators"] = [HREFValidator()]
+        super().__init__(*args, **kwargs)
+
+
+class HREFBlock(URLBlock):
+    """Custom block for href attributes (i.e. a `URLBlock` using the extended `HREFField`)."""
+
+    def __init__(self, *args, **kwargs) -> None:  # noqa: ANN002, ANN003
+        """Initialise the `URLBlock` superclass and replace our field with a `HREFField`."""
+        super().__init__(*args, **kwargs)
+        self.field = HREFField()
+
+
+class StaticIconLinkItemBlock(StructBlock):
+    """A single list item with an optional icon and surrounding anchor."""
+
+    href = HREFBlock(
+        required=False,
+        help_text="An optional link field",
+        max_length=255,
+    )
+    label = CharBlock(required=True, max_length=50, help_text="The title for the list item.")
+    icon = CharBlock(
+        required=False,
+        max_length=255,
+        help_text="Id of the icon in the static/icons.svg file.",
+    )
+
+    class Meta:
+        """Meta information."""
+
+        template = "picata/blocks/icon_link_item.html"
+
+
+class StaticIconLinkListBlock(StructBlock):
+    """A list of optionally-linked list items with an optional heading."""
+
+    heading = CharBlock(
+        required=False,
+        help_text="Optional heading for this list (e.g., Social Links).",
+    )
+    heading_level = IntegerBlock(
+        required=False,
+        min_value=1,
+        max_value=6,
+        default=2,
+        help_text="Heading level for the list (1-6).",
+    )
+    items = ListBlock(
+        StaticIconLinkItemBlock(),
+        help_text="The list of items.",
+    )
+
+    class Meta:
+        """Meta information."""
+
+        template = "picata/blocks/icon_link_list.html"
+
+
+class StaticIconLinkListsBlock(StructBlock):
+    """A wrapper for multiple heading-and-link-list blocks."""
+
+    lists = StreamBlock(
+        [
+            ("link_list", StaticIconLinkListBlock()),
+        ],
+        required=False,
+        help_text="Add one or more heading-and-link-list blocks.",
+    )
+
+    class Meta:
+        """Meta information."""
+
+        template = "picata/blocks/icon_link_list_stream.html"
+
+
+class CodeBlock(StructBlock):
+    """A block for displaying code with optional syntax highlighting."""
+
+    code = TextBlock(required=True, help_text=None)
+    language = ChoiceBlock(
+        required=False,
+        choices=[
+            ("python", "Python"),
+            ("javascript", "JavaScript"),
+            ("html", "HTML"),
+            ("css", "CSS"),
+            ("bash", "Bash"),
+            ("plaintext", "Plain Text"),
+        ],
+        help_text=None,
+    )
+
+    def render_basic(self, value: BlockRenderValue, context: BlockRenderContext = None) -> str:
+        """Render the code block with syntax highlighting."""
+        code = value.get("code", "")
+        language = value.get("language", "plaintext")
+        try:
+            lexer = lexers.get_lexer_by_name(language)
+            formatter = formatters.HtmlFormatter(cssclass="pygments")
+            highlighted_code = pygments.highlight(code, lexer, formatter)
+        except ClassNotFound:
+            highlighted_code = f"<pre><code>{code}</code></pre>"
+
+        return format_html(highlighted_code)
+
+    class Meta:
+        """Meta information."""
+
+        icon = "code"
+        label = "Code Block"
+
+
+class SectionBlock(StructBlock):
+    """A page section, with a heading rendered at a defined level."""
+
+    heading = CharBlock(
+        required=True, help_text='Heading for this section, included in "page contents".'
+    )
+    level = IntegerBlock(required=True, min_value=1, max_value=6, help_text="Heading level")
+    content = StreamBlock(
+        [
+            ("rich_text", RichTextBlock()),
+            ("image", ImageChooserBlock()),
+        ],
+        required=False,
+        help_text=None,
+    )
+
+    class Meta:
+        """Meta-info for the block."""
+
+        icon = "folder"
+        label = "Section"
+
+
+class WrappedImageChooserBlock(ImageChooserBlock):
+    """An ImageChooserBlock that wraps the output in a div."""
+
+    def render_basic(self, value: BlockRenderValue, context: BlockRenderContext = None) -> str:
+        """Render the image wrapped in a div with a custom class."""
+        if not value:  # If no image is selected, return an empty string
+            return ""
+
+        # Use Wagtail's default rendering for the image, wrapped in a <div>
+        image_tag = super().render_basic(value, context)
+        return f'<div class="image-wrapper">{image_tag}</div>'

picata/helpers/__init__.py

@@ -0,0 +1,70 @@
+"""Generic helper-functions."""
+# NB: Django's meta-class shenanigans over-complicate type hinting when QuerySets get involved.
+# pyright: reportAttributeAccessIssue=false
+
+import re
+from ipaddress import AddressValueError, IPv4Address
+
+from django.apps import apps
+from django.db.models import Model
+from django.http import HttpResponse, StreamingHttpResponse
+from lxml.etree import _Element
+
+# Pre-compile commonly used regular expressions
+ALPHANUMERIC_REGEX = re.compile(r"[^a-zA-Z0-9]")
+
+
+def get_models_of_type(base_type: type[Model]) -> list[type[Model]]:
+    """Retrieve all concrete subclasses of the given base Model type."""
+    all_models = apps.get_models()
+
+    return [
+        model
+        for model in all_models
+        if issubclass(model, base_type) and not model._meta.abstract  # noqa: SLF001
+    ]
+
+
+def get_public_ip() -> IPv4Address | None:
+    """Fetch the public-facing IP of the current host."""
+    import socket
+
+    import psutil
+
+    for addrs in psutil.net_if_addrs().values():
+        for addr in addrs:
+            if addr.family == socket.AF_INET:
+                ip = addr.address
+                if not ip.startswith(("10.", "192.168.", "172.", "127.")):
+                    try:
+                        return IPv4Address(ip)
+                    except AddressValueError:
+                        pass
+    return None
+
+
+def get_full_text(element: _Element) -> str:
+    """Extract text from an element and its descendants, concatenate it, and trim whitespace."""
+    return "".join(element.xpath(".//text()")).strip()
+
+
+def make_response(
+    original_response: HttpResponse,
+    new_content: str | bytes,
+) -> HttpResponse:
+    """Create a new HttpResponse while preserving attributes from the original response."""
+    if isinstance(original_response, StreamingHttpResponse):
+        raise TypeError("StreamingHttpResponse objects are not supported.")
+    new_response = HttpResponse(
+        content=new_content,
+        content_type=original_response.get("Content-Type", None),
+        status=original_response.status_code,
+    )
+    for key, value in original_response.headers.items():
+        new_response[key] = value
+    new_response.cookies = original_response.cookies
+    for attr in dir(original_response):
+        if not attr.startswith("_") and not hasattr(HttpResponse, attr):
+            setattr(new_response, attr, getattr(original_response, attr))
+
+    return new_response