diff options
| -rw-r--r-- | docs/superpowers/specs/2026-05-14-packages-shortcodes-design.md | 149 |
1 files changed, 149 insertions, 0 deletions
diff --git a/docs/superpowers/specs/2026-05-14-packages-shortcodes-design.md b/docs/superpowers/specs/2026-05-14-packages-shortcodes-design.md new file mode 100644 index 0000000..2e56bad --- /dev/null +++ b/docs/superpowers/specs/2026-05-14-packages-shortcodes-design.md @@ -0,0 +1,149 @@ +# Design: packages.danix.xyz Shortcodes + +**Date:** 2026-05-14 +**Status:** Approved + +## Overview + +Two Alpine.js shortcodes for the repository page that fetch live data from `packages.danix.xyz` and render it in the browser. Data updates on every page load without a site rebuild. + +## Prerequisites + +### CORS (manual step — not in theme) + +Add to Apache config on `packages.danix.xyz`: + +```apache +Header set Access-Control-Allow-Origin "https://danix.xyz" +``` + +Without this header, browser fetch from `danix.xyz` will be blocked by CORS policy. + +--- + +## Shortcode 1: `pkg-list` + +### Usage + +``` +{{< pkg-list >}} +``` + +No parameters. Fetches from hardcoded `https://packages.danix.xyz/PACKAGES.TXT`. + +### File + +`themes/danix-xyz-hacker/layouts/shortcodes/pkg-list.html` + +### Behavior + +- On mount, Alpine fetches `PACKAGES.TXT` via `fetch()` +- Parses repeating blocks: extracts `PACKAGE NAME` and `PACKAGE LOCATION` lines +- Parses filename to extract short name and version: + - Input: `waybar-0.14.0-x86_64-2_danix.txz` + - Output: name=`waybar`, version=`0.14.0` +- Derives category and folder link from `PACKAGE LOCATION` (e.g. `./desktop/waybar` → `https://packages.danix.xyz/desktop/waybar/`) +- Renders a filterable table + +### Table columns + +| Name | Version | Link | +|------|---------|------| +| waybar | 0.14.0 | → packages.danix.xyz/desktop/waybar/ | + +- **Name**: parsed short name (before first version segment) +- **Version**: first version segment from filename +- **Link**: anchor pointing to folder on packages.danix.xyz, label is `category/name` + +### Filter + +Text input above table. Filters by name, client-side, no server round-trips. + +### States + +1. **Loading**: spinner + i18n loading string +2. **Loaded**: filter input + table +3. **Error**: styled error block + fallback link to `https://packages.danix.xyz` + +### i18n keys (new) + +```yaml +pkg_list_loading: "Loading packages..." # it: "Caricamento pacchetti..." +pkg_list_error: "Could not load packages." # it: "Impossibile caricare i pacchetti." +pkg_list_filter: "Filter packages..." # it: "Filtra pacchetti..." +pkg_list_link_label: "View" # it: "Visualizza" +``` + +--- + +## Shortcode 2: `pkg-changelog` + +### Usage + +``` +{{< pkg-changelog count="10" >}} +``` + +`count`: number of entries to display. Default: `10`. + +### File + +`themes/danix-xyz-hacker/layouts/shortcodes/pkg-changelog.html` + +### Behavior + +- On mount, Alpine fetches `https://packages.danix.xyz/ChangeLog.txt` via `fetch()` +- Splits on `+--------------------------+` delimiter to get individual entries +- Discards empty chunks; takes first N (from `count` param rendered into `x-data`) +- Each chunk: first non-empty line = timestamp, remaining lines = change description + +### Timeline rendering + +Vertical timeline with purple accent dots (theme `primaryAccent` color `#a855f7`): + +``` +│ +◉ Thu May 14 17:17:42 UTC 2026 +│ personal/python3-platformdirs/...: Updated for git 7836e58 +│ +◉ Thu May 14 17:02:54 UTC 2026 +│ personal/nvchecker/...: Added version 2.20. +``` + +- Dot: `◉` or CSS circle marker, purple accent color +- Timestamp: bold, readable date +- Change text: monospace, preserves whitespace/line breaks from source + +### States + +1. **Loading**: spinner + i18n loading string +2. **Loaded**: timeline +3. **Error**: styled error block + fallback link to `https://packages.danix.xyz/ChangeLog.txt` + +### i18n keys (new) + +```yaml +pkg_changelog_loading: "Loading changelog..." # it: "Caricamento changelog..." +pkg_changelog_error: "Could not load changelog." # it: "Impossibile caricare il changelog." +``` + +--- + +## File Checklist + +| File | Action | +|------|--------| +| `themes/danix-xyz-hacker/layouts/shortcodes/pkg-list.html` | Create | +| `themes/danix-xyz-hacker/layouts/shortcodes/pkg-changelog.html` | Create | +| `themes/danix-xyz-hacker/i18n/en.yaml` | Add i18n keys | +| `themes/danix-xyz-hacker/i18n/it.yaml` | Add i18n keys | +| `packages.danix.xyz` Apache config | Add CORS header (manual) | +| `content/en/repository/index.md` | Add shortcode calls | +| `content/it/repository/index.md` | Add shortcode calls | + +## Out of Scope + +- CSS rebuild (`npm run build`) required if shortcodes introduce Tailwind classes not already in `main.min.css`; use existing utility classes where possible to avoid this +- No new JS files — logic lives inline in shortcode templates +- No sorting (filter only for pkg-list) +- No pagination (count param caps changelog entries) |