@fikar-ai/design 1.5.0

package/recipes/user-menu.html

@@ -0,0 +1,21 @@
+<!-- User menu: the avatar and account panel, last in the top bar cluster. Shown here signed in with a name, no picture and an extra item.
+     With a picture the initials span becomes <img class="avatar" src="..." alt="">, and data-initials stays, because shell.js swaps a broken picture for the initials. With no name, the .user-menu-id block holds the email once
+     and has no .user-menu-email. Account settings is optional, extra items go after it, and Sign out is last. The second separator is only
+     there when something comes before Sign out. Sign out may also be <button class="launcher-item user-menu-item" type="button" role="menuitem">.
+     data-fk-menu opts in to the behaviour in shell.js; leave it off when the page wires the menu itself. -->
+<div class="launcher" data-fk-menu>
+  <button class="user-menu-btn" type="button" aria-haspopup="menu" aria-expanded="false" aria-label="Open account menu" data-initials="AM">
+    <span class="avatar" aria-hidden="true">AM</span>
+  </button>
+  <div class="launcher-panel user-menu-panel" role="menu">
+    <div class="user-menu-id">
+      <span class="user-menu-name">Alex Morgan</span>
+      <span class="user-menu-email">alex@example.com</span>
+    </div>
+    <div class="user-menu-sep" role="separator"></div>
+    <a class="launcher-item user-menu-item" role="menuitem" href="/account">Account settings</a>
+    <a class="launcher-item user-menu-item" role="menuitem" href="/workspace">Workspace settings</a>
+    <div class="user-menu-sep" role="separator"></div>
+    <a class="launcher-item user-menu-item" role="menuitem" href="/logout">Sign out</a>
+  </div>
+</div>

package/shell.js

@@ -0,0 +1,324 @@
+/* @fikar-ai/design app shell behaviour. Classic script, no dependencies.
+   Binds the classes documented in the README: .shell, .shell-menu, .shell-close,
+   .shell-scrim, .shell-collapse, any menu that opts in with data-fk-menu, and the search
+   box that registers with data-fk-search.
+   Exposes window.FikarShell.init(root), and the two time formatters formatRelative and formatExact (KAN-342). */
+(function () {
+  'use strict';
+
+  var KEY = 'fikar.shell.collapsed';
+  var DESKTOP = '(min-width: 1024px)';
+  var bound = new WeakSet();
+  var boundMenus = new WeakSet();
+  var menuKeysBound = false;
+  var desktop = window.matchMedia ? window.matchMedia(DESKTOP) : null;
+
+  // Reading or writing storage can throw (private mode, blocked site data).
+  // The class on the element is the state for the session, so every failure is safe to ignore.
+  function readCollapsed() {
+    try { return window.localStorage.getItem(KEY) === '1'; } catch (e) { return false; }
+  }
+  function writeCollapsed(on) {
+    // Writes "0" on expand, like @fikar-ai/design-react, so both behave the same.
+    // A removed key and "0" are both read as open.
+    try { window.localStorage.setItem(KEY, on ? '1' : '0'); } catch (e) { /* see readCollapsed */ }
+  }
+
+  function isDesktop() {
+    return desktop ? desktop.matches : true;
+  }
+
+  // A .no-sidebar shell has no drawer or collapse control, so there is nothing to bind and no state to
+  // restore. Skipping it also keeps a stored "1" from putting .is-collapsed on it.
+  function shellsIn(root) {
+    var found = Array.prototype.slice.call(root.querySelectorAll('.shell'));
+    if (root.classList && root.classList.contains('shell')) found.unshift(root);
+    return found.filter(function (shell) { return !shell.classList.contains('no-sidebar'); });
+  }
+
+  function setCollapsed(shell, toggle, on) {
+    shell.classList.toggle('is-collapsed', on);
+    if (!toggle) return;
+    toggle.setAttribute('aria-pressed', on ? 'true' : 'false');
+    toggle.setAttribute('title', on ? 'Expand sidebar' : 'Collapse sidebar');
+  }
+
+  function bind(shell) {
+    if (bound.has(shell)) return;
+    bound.add(shell);
+
+    var menu = shell.querySelector('.shell-menu');
+    var close = shell.querySelector('.shell-close');
+    var scrim = shell.querySelector('.shell-scrim');
+    var toggle = shell.querySelector('.shell-collapse');
+
+    function setOpen(on, returnFocus) {
+      shell.classList.toggle('nav-open', on);
+      if (menu) menu.setAttribute('aria-expanded', on ? 'true' : 'false');
+      if (scrim) {
+        if (on) scrim.removeAttribute('hidden');
+        else scrim.setAttribute('hidden', '');
+      }
+      if (!on && returnFocus && menu) menu.focus();
+    }
+    function isOpen() {
+      return shell.classList.contains('nav-open');
+    }
+
+    setCollapsed(shell, toggle, readCollapsed());
+
+    if (toggle) {
+      toggle.addEventListener('click', function () {
+        // The rule only applies from 1024px and the control is hidden below it.
+        if (!isDesktop()) return;
+        var on = !shell.classList.contains('is-collapsed');
+        setCollapsed(shell, toggle, on);
+        writeCollapsed(on);
+      });
+    }
+    if (menu) menu.addEventListener('click', function () { setOpen(true, false); });
+    if (close) close.addEventListener('click', function () { setOpen(false, true); });
+    if (scrim) scrim.addEventListener('click', function () { setOpen(false, true); });
+
+    document.addEventListener('keydown', function (e) {
+      if (e.key === 'Escape' && isOpen()) setOpen(false, true);
+    });
+
+    // Growing past 1024px hides the menu button, so the scrim would otherwise
+    // stay over the page with no visible way to dismiss it.
+    if (desktop) {
+      var onChange = function () { if (desktop.matches && isOpen()) setOpen(false, false); };
+      if (desktop.addEventListener) desktop.addEventListener('change', onChange);
+      else if (desktop.addListener) desktop.addListener(onChange);
+    }
+  }
+
+  // Menus: any element with data-fk-menu, such as the launcher, the theme menu and the user menu. The root carries .open, the first
+  // [aria-haspopup] inside it is the trigger, and [role="menuitem"] and [role="menuitemradio"] are the rows. Nothing here runs on a
+  // page with no such element, and a menu the page wires itself has no data-fk-menu, so it is never handled twice.
+  var MENU = '[data-fk-menu]';
+  var RADIO = '[role="menuitemradio"]';
+  var ITEM = '[role="menuitem"],' + RADIO;
+
+  function menusIn(root) {
+    var found = Array.prototype.slice.call(root.querySelectorAll(MENU));
+    if (root.hasAttribute && root.hasAttribute('data-fk-menu')) found.unshift(root);
+    return found;
+  }
+
+  function openMenus() {
+    return Array.prototype.slice.call(document.querySelectorAll(MENU + '.open'));
+  }
+
+  function setMenuOpen(menu, on, returnFocus) {
+    var trigger = menu.querySelector('[aria-haspopup]');
+    menu.classList.toggle('open', on);
+    if (!trigger) return;
+    trigger.setAttribute('aria-expanded', on ? 'true' : 'false');
+    if (!on && returnFocus) trigger.focus();
+  }
+
+  function itemOf(menu, node) {
+    for (; node && node !== menu; node = node.parentNode) {
+      var role = node.getAttribute && node.getAttribute('role');
+      if (role === 'menuitem' || role === 'menuitemradio') return node;
+    }
+    return null;
+  }
+
+  // The only radio menu is the theme menu. The chosen row takes .current and aria-checked at once, so the page needs no code to show
+  // it, and the page hears about a change on the menu root as a bubbling fk-theme-change event with the row's data-value in detail.value.
+  // Choosing the row that is already checked changes nothing and sends nothing.
+  function choose(menu, row) {
+    if (row.getAttribute('aria-checked') === 'true') return;
+    Array.prototype.forEach.call(menu.querySelectorAll(RADIO), function (other) {
+      other.classList.toggle('current', other === row);
+      other.setAttribute('aria-checked', other === row ? 'true' : 'false');
+    });
+    menu.dispatchEvent(new window.CustomEvent('fk-theme-change', { bubbles: true, detail: { value: row.getAttribute('data-value') } }));
+  }
+
+  // A picture that fails to load is swapped for the initials the markup carries in data-initials on the trigger.
+  // The span is the same one the markup has when there is no picture. error does not bubble, so it is bound on the image,
+  // and an image that failed before this ran is caught by complete with no width.
+  function showInitialsIfBroken(trigger) {
+    var img = trigger.querySelector('img');
+    var initials = trigger.getAttribute('data-initials');
+    if (!img || !initials) return;
+    function swap() {
+      var span = document.createElement('span');
+      span.className = 'avatar';
+      span.setAttribute('aria-hidden', 'true');
+      span.textContent = initials;
+      trigger.replaceChild(span, img);
+    }
+    if (img.complete && img.naturalWidth === 0) swap();
+    else img.addEventListener('error', swap);
+  }
+
+  function bindMenu(menu) {
+    if (boundMenus.has(menu)) return;
+    boundMenus.add(menu);
+
+    var trigger = menu.querySelector('[aria-haspopup]');
+    if (trigger) {
+      showInitialsIfBroken(trigger);
+      trigger.addEventListener('click', function () {
+        var on = !menu.classList.contains('open');
+        // Opening one menu closes the others, so two panels are never open at once.
+        if (on) openMenus().forEach(function (other) { if (other !== menu) setMenuOpen(other, false, false); });
+        setMenuOpen(menu, on, false);
+      });
+    }
+    // A chosen row closes the panel and leaves focus with whatever the row does (a link navigates, a button acts).
+    // A radio row acts on the menu itself and there is nowhere else for focus to go, so it returns to the trigger.
+    menu.addEventListener('click', function (e) {
+      var item = itemOf(menu, e.target);
+      if (!item) return;
+      var radio = item.getAttribute('role') === 'menuitemradio';
+      if (radio) choose(menu, item);
+      setMenuOpen(menu, false, radio);
+    });
+    bindMenuKeys();
+  }
+
+  // One pair of document listeners serves every menu, added when the first menu is bound.
+  function bindMenuKeys() {
+    if (menuKeysBound) return;
+    menuKeysBound = true;
+
+    // pointerdown rather than click: iOS Safari does not deliver click to the document for taps on non-interactive elements.
+    document.addEventListener('pointerdown', function (e) {
+      openMenus().forEach(function (menu) { if (!menu.contains(e.target)) setMenuOpen(menu, false, false); });
+    });
+
+    document.addEventListener('keydown', function (e) {
+      var menu = openMenus()[0];
+      if (!menu) return;
+      if (e.key === 'Escape') {
+        setMenuOpen(menu, false, true);
+        return;
+      }
+      var items = Array.prototype.slice.call(menu.querySelectorAll(ITEM));
+      var at = items.indexOf(document.activeElement);
+      var next = { ArrowDown: at + 1, ArrowUp: at < 0 ? items.length - 1 : at - 1, Home: 0, End: items.length - 1 }[e.key];
+      if (next === undefined || !items.length || !menu.contains(document.activeElement)) return;
+      e.preventDefault();
+      items[(next + items.length) % items.length].focus();
+    });
+  }
+
+  // Search (since 1.3.0): the page registers one search box by putting data-fk-search on its input, and / or Cmd-K or Ctrl-K focuses it. Both modifiers
+  // are accepted on every platform, so nothing sniffs the operating system, and Cmd-K works from any focus while / is left alone in a field. The first
+  // registered box that is on screen wins, so a second one is never chosen and a box hidden at a narrow width is skipped. Nothing here runs on a page with no
+  // registered box and no .search-clear, and a page that wires its own clear button is not handled twice, since clearing twice changes nothing.
+  var SEARCH = '[data-fk-search]';
+  var searchBound = false;
+
+  function isTyping(node) {
+    return !!node && (/^(INPUT|TEXTAREA|SELECT)$/.test(node.tagName) || node.isContentEditable === true);
+  }
+
+  function searchBox() {
+    var boxes = document.querySelectorAll(SEARCH);
+    for (var i = 0; i < boxes.length; i++) if (boxes[i].getClientRects().length > 0) return boxes[i];
+    return null;
+  }
+
+  function focusSearch(e) {
+    if (e.defaultPrevented || e.isComposing || e.altKey) return;
+    var slash = e.key === '/' && !e.ctrlKey && !e.metaKey;
+    var palette = (e.key === 'k' || e.key === 'K') && (e.metaKey || e.ctrlKey);
+    if (!slash && !palette) return;
+    if (slash && isTyping(e.target)) return;
+    var box = searchBox();
+    if (!box) return;
+    // Without this the / would be typed into the box that has just taken focus, and Ctrl-K would reach the browser's own bar.
+    e.preventDefault();
+    box.focus();
+    box.select();
+  }
+
+  // Empties the box, tells the page (a plain input event, so its own listeners hear it), and keeps focus in the box so typing can go on.
+  function clearSearch(e) {
+    for (var node = e.target; node; node = node.parentNode) {
+      if (!node.classList || !node.classList.contains('search-clear')) continue;
+      var input = node.parentNode.querySelector('input');
+      if (!input) return;
+      input.value = '';
+      input.dispatchEvent(new window.Event('input', { bubbles: true }));
+      input.focus();
+      return;
+    }
+  }
+
+  function bindSearch(root) {
+    if (searchBound) return;
+    var here = root.querySelector(SEARCH + ',.search-clear') || (root.hasAttribute && root.hasAttribute('data-fk-search'));
+    if (!here) return;
+    searchBound = true;
+    document.addEventListener('keydown', focusSearch);
+    document.addEventListener('click', clearSearch);
+  }
+
+  // Time (KAN-342): the one wording for a moment that every surface uses, so a page never formats it on its own. formatRelative says "just now" under a
+  // minute, "4 min ago" under an hour and "4 h ago" under a day, and after that gives formatExact, "22 Sep, 08:16" in the reader's time zone on a 24 hour
+  // clock, with the year ("22 Sep 2025, 08:16") once the moment is a year or more from now. A moment more than a minute ahead is also given exactly, since a
+  // clock that is a few seconds fast is common and a real future date is not "ago". The month names are written out because Intl gives "Sept" for
+  // September in en-GB. The same rules are in @fikar-ai/design-react (format-time.ts), and test/fixtures/time-rules.json holds the table both are tested against.
+  // `value` is a Date or an ISO string, `now` (a Date, for tests) defaults to the current time, and a value that is not a date gives an empty string.
+  var MONTHS = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
+  var MINUTE = 60000;
+  var HOUR = 60 * MINUTE;
+  var DAY = 24 * HOUR;
+  var YEAR = 365 * DAY;
+
+  function toTime(value) {
+    return new Date(value).getTime();
+  }
+
+  function two(n) {
+    return n < 10 ? '0' + n : String(n);
+  }
+
+  function formatExact(value, now) {
+    var time = toTime(value);
+    if (isNaN(time)) return '';
+    var date = new Date(time);
+    var year = Math.abs((now === undefined ? Date.now() : toTime(now)) - time) >= YEAR ? ' ' + date.getFullYear() : '';
+    return date.getDate() + ' ' + MONTHS[date.getMonth()] + year + ', ' + two(date.getHours()) + ':' + two(date.getMinutes());
+  }
+
+  function formatRelative(value, now) {
+    var time = toTime(value);
+    if (isNaN(time)) return '';
+    var age = (now === undefined ? Date.now() : toTime(now)) - time;
+    if (age < -MINUTE || age >= DAY) return formatExact(value, now);
+    if (age < MINUTE) return 'just now';
+    if (age < HOUR) return Math.floor(age / MINUTE) + ' min ago';
+    return Math.floor(age / HOUR) + ' h ago';
+  }
+
+  function init(root) {
+    var scope = root || document;
+    shellsIn(scope).forEach(bind);
+    menusIn(scope).forEach(bindMenu);
+    bindSearch(scope);
+  }
+
+  // Runs while the document is still parsing. Only the class is touched, because
+  // the rest of the shell may not exist yet. Full binding waits for the whole tree.
+  function restoreEarly() {
+    if (!readCollapsed()) return;
+    shellsIn(document).forEach(function (shell) { shell.classList.add('is-collapsed'); });
+  }
+
+  window.FikarShell = { init: init, formatRelative: formatRelative, formatExact: formatExact };
+
+  if (document.readyState === 'loading') {
+    restoreEarly();
+    document.addEventListener('DOMContentLoaded', function () { init(document); });
+  } else {
+    init(document);
+  }
+})();

package/templates/jinja/launcher.html

@@ -0,0 +1,45 @@
+{#- App launcher, same markup as recipes/launcher.html. Renders nothing for an empty list.
+
+    {% from "fikar/launcher.html" import launcher %}
+    {{ launcher(apps) }}
+    {{ launcher(apps, data_fk_menu=true) }}
+
+    apps          list of items: label, href, id, and optional current (bool), already filtered and ordered by the host. The id picks the glyph
+                  (chat, platform, crs, dictionary, cost-calculator, super-admin, account), and an item with no id, or one the package does
+                  not know, shows the first letter of its label in the same tile. A hint is accepted and not rendered (since 1.5.0).
+    data_fk_menu  optional, default false. True puts data-fk-menu on the root so shell.js opens and closes it. The default output is
+                  free of the attribute, so a page that wires the launcher itself and updates the package is not handled twice.
+                  Set it only once the page's own wiring is removed, and on every menu in the page (see "Moving a page to shell.js" in the README) -#}
+{#- The glyph map below is generated from brand/apps/*.svg. Do not edit it here: change the SVG and run `node scripts/build-app-icons.mjs`. -#}
+{#- generated:app-icons begin (scripts/build-app-icons.mjs, from brand/apps/*.svg) -#}
+{% set app_icons = {
+  'account': '<circle cx="12" cy="8" r="5"/><path d="M20 21a8 8 0 0 0-16 0"/>',
+  'chat': '<path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/>',
+  'cost-calculator': '<rect width="16" height="20" x="4" y="2" rx="2"/><line x1="8" x2="16" y1="6" y2="6"/><line x1="16" x2="16" y1="14" y2="18"/><path d="M16 10h.01"/><path d="M12 10h.01"/><path d="M8 10h.01"/><path d="M12 14h.01"/><path d="M8 14h.01"/><path d="M12 18h.01"/><path d="M8 18h.01"/>',
+  'crs': '<circle cx="12" cy="4.5" r="2.5"/><path d="m10.2 6.3-3.9 3.9"/><circle cx="4.5" cy="12" r="2.5"/><path d="M7 12h10"/><circle cx="19.5" cy="12" r="2.5"/><path d="m13.8 17.7 3.9-3.9"/><circle cx="12" cy="19.5" r="2.5"/>',
+  'dictionary': '<path d="M4 19.5v-15A2.5 2.5 0 0 1 6.5 2H19a1 1 0 0 1 1 1v18a1 1 0 0 1-1 1H6.5a1 1 0 0 1 0-5H20"/><path d="m8 13 4-7 4 7"/><path d="M9.1 11h5.7"/>',
+  'platform': '<line x1="21" x2="14" y1="4" y2="4"/><line x1="10" x2="3" y1="4" y2="4"/><line x1="21" x2="12" y1="12" y2="12"/><line x1="8" x2="3" y1="12" y2="12"/><line x1="21" x2="16" y1="20" y2="20"/><line x1="12" x2="3" y1="20" y2="20"/><line x1="14" x2="14" y1="2" y2="6"/><line x1="8" x2="8" y1="10" y2="14"/><line x1="16" x2="16" y1="18" y2="22"/>',
+  'super-admin': '<path d="M6 22V4a2 2 0 0 1 2-2h8a2 2 0 0 1 2 2v18Z"/><path d="M6 12H4a2 2 0 0 0-2 2v6a2 2 0 0 0 2 2h2"/><path d="M18 9h2a2 2 0 0 1 2 2v9a2 2 0 0 1-2 2h-2"/><path d="M10 6h4"/><path d="M10 10h4"/><path d="M10 14h4"/><path d="M10 18h4"/>',
+} %}
+{#- generated:app-icons end -#}
+{% macro launcher(apps, data_fk_menu=false) -%}
+{%- if apps %}
+<div class="launcher"{{ ' data-fk-menu' if data_fk_menu }}>
+  <button class="launcher-btn" type="button" aria-haspopup="menu" aria-expanded="false" aria-label="Switch app">
+    <svg viewBox="0 0 24 24" fill="currentColor" aria-hidden="true">
+      <circle cx="5" cy="5" r="2"/><circle cx="12" cy="5" r="2"/><circle cx="19" cy="5" r="2"/>
+      <circle cx="5" cy="12" r="2"/><circle cx="12" cy="12" r="2"/><circle cx="19" cy="12" r="2"/>
+      <circle cx="5" cy="19" r="2"/><circle cx="12" cy="19" r="2"/><circle cx="19" cy="19" r="2"/>
+    </svg>
+  </button>
+  <div class="launcher-panel launcher-apps" role="menu">
+    {%- for app in apps %}
+    {%- set body = app_icons.get(app.id) if app.id else none %}
+    <a class="launcher-item{{ ' current' if app.current }}" role="menuitem" href="{{ app.href }}"{{ ' aria-current="page"'|safe if app.current }}>
+      <span class="launcher-tile" aria-hidden="true">{% if body %}<svg class="app-icon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">{{ body|safe }}</svg>{% else %}{{ (app.label or '')[:1]|upper }}{% endif %}</span>{{ app.label }}
+    </a>
+    {%- endfor %}
+  </div>
+</div>
+{%- endif %}
+{%- endmacro %}

package/templates/jinja/shell.html

@@ -0,0 +1,97 @@
+{#- App shell, same markup as recipes/shell.html. No host logic: everything comes in as arguments.
+
+    {% from "fikar/shell.html" import shell %}
+    {% call shell(brand=brand, nav=nav, foot=foot, cluster=cluster, start=start, scroll=true) %}page content{% endcall %}
+
+    brand    markup for the logo and word, used in the sidebar and in the top bar
+    nav      list of entries. An item has label, href, icon (svg markup), and optional active (bool), title (defaults
+             to label), badge (text) and class (extra class names, after nav-item and active; use nav-item-back for
+             the link back to the app the person came from). An entry with heading: true and a label is a group
+             heading instead.
+    foot     optional markup for the side foot. Nothing renders when it is empty or only whitespace, so there is no bare divider.
+    cluster  markup for the top bar cluster (launcher, theme control, avatar menu, in that order)
+    start    optional markup for the top bar, left of the cluster (a search box, a page title). Nothing renders when empty.
+    scroll   optional bool. True makes the nav scroll inside the sidebar, for long lists.
+    nav_label  optional accessible name of the sidebar nav. Default 'Main'.
+    fill     optional bool. True adds is-fill: the shell is one viewport tall at every width, and the main area is a
+             padless column for a page that scrolls inside itself (a conversation with a docked composer).
+
+    Markup arguments must be marked safe (Markup, |safe, or a {% set x %} block) when autoescape is on.
+    The call body is the main content. -#}
+{% macro shell(brand, nav, foot, cluster, start='', scroll=false, nav_label='Main', fill=false) -%}
+<div class="shell with-topbar{{ ' is-fill' if fill }}" id="shell">
+  <aside class="sidebar" id="sidebar">
+    <div class="brand">
+      {{ brand }}
+      <button class="shell-close iconbtn" type="button" aria-label="Close navigation">&times;</button>
+    </div>
+    <nav class="side{{ ' is-scroll' if scroll }}" aria-label="{{ nav_label }}">
+      {%- for item in nav %}
+      {%- if item.heading %}
+      <div class="nav-heading">{{ item.label }}</div>
+      {%- else %}
+      <a class="nav-item{{ ' active' if item.active }}{{ ' ' ~ item['class'] if item['class'] }}" href="{{ item.href }}" title="{{ item.title or item.label }}"{{ ' aria-current="page"'|safe if item.active }}>
+        {{ item.icon }}
+        <span class="nav-label">{{ item.label }}</span>
+        {%- if item.badge %}
+        <span class="nav-badge">{{ item.badge }}</span>
+        {%- endif %}
+      </a>
+      {%- endif %}
+      {%- endfor %}
+    </nav>
+    {%- if foot and foot|trim %}
+    <div class="side-foot">
+      {{ foot }}
+    </div>
+    {%- endif %}
+    <button class="shell-collapse" type="button" aria-controls="sidebar" aria-pressed="false" title="Collapse sidebar">
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M15 6l-6 6 6 6"/></svg>
+      <span class="nav-label">Collapse</span>
+    </button>
+  </aside>
+  <header class="shell-topbar">
+    <button class="shell-menu" type="button" aria-label="Open navigation" aria-controls="sidebar" aria-expanded="false">
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" aria-hidden="true"><path d="M4 6h16M4 12h16M4 18h16"/></svg>
+    </button>
+    <div class="brand">{{ brand }}</div>
+    {%- if start %}
+    <div class="shell-topbar-start">{{ start }}</div>
+    {%- endif %}
+    <div class="cluster">
+      {{ cluster }}
+    </div>
+  </header>
+  <div class="shell-scrim" hidden></div>
+  <main class="main"><div class="content">{{ caller() }}</div></main>
+</div>
+{%- endmacro %}
+
+
+{#- The shell for an app with a top bar and no sidebar. Same markup as recipes/shell-no-sidebar.html.
+
+    {% from "fikar/shell.html" import topbar_shell %}
+    {% call topbar_shell(brand=brand, cluster=cluster, start=start) %}page content{% endcall %}
+
+    brand    markup for the logo and word, shown in the top bar at every width
+    cluster  markup for the top bar cluster (launcher, theme control, avatar menu, in that order)
+    start    optional markup between the brand and the cluster, such as a pill and a row of links. It scrolls sideways
+             inside itself when the bar is short of room. Nothing renders when empty.
+    fill     optional bool, as on shell()
+
+    There is no nav, foot or scroll argument because there is no sidebar to put them in. The call body is the main content.
+    shell.js skips this markup: it has no drawer and no collapse control. -#}
+{% macro topbar_shell(brand, cluster, start='', fill=false) -%}
+<div class="shell with-topbar no-sidebar{{ ' is-fill' if fill }}" id="shell">
+  <header class="shell-topbar">
+    <div class="brand">{{ brand }}</div>
+    {%- if start %}
+    <div class="shell-topbar-start">{{ start }}</div>
+    {%- endif %}
+    <div class="cluster">
+      {{ cluster }}
+    </div>
+  </header>
+  <main class="main"><div class="content">{{ caller() }}</div></main>
+</div>
+{%- endmacro %}

package/templates/jinja/theme-menu.html

@@ -0,0 +1,27 @@
+{#- Theme menu, same markup as recipes/theme-menu.html. Goes second in the shell cluster, after the launcher and before the user menu.
+
+    {% from "fikar/theme-menu.html" import theme_menu %}
+    {{ theme_menu(value=me.theme) }}
+
+    value  the theme the person has now, 'light', 'dark' or 'system'. Anything else, including none, is shown as 'system'
+
+    The menu stores nothing. shell.js sends a bubbling fk-theme-change event from the root with the chosen value in detail.value, and the page applies and saves it.
+    The root carries data-fk-menu, so shell.js handles opening and closing. Leave it out of a host that wires the menu itself. -#}
+{% macro theme_menu(value='system') -%}
+{%- set current = value if value in ['light', 'dark'] else 'system' %}
+<div class="launcher" data-fk-menu>
+  <button class="launcher-btn theme-menu-btn" type="button" aria-haspopup="menu" aria-expanded="false" aria-label="Choose theme">
+    <svg class="theme-icon-sun" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+      <circle cx="12" cy="12" r="4"/><path d="M12 2v2M12 20v2M4.93 4.93l1.41 1.41M17.66 17.66l1.41 1.41M2 12h2M20 12h2M6.34 17.66l-1.41 1.41M19.07 4.93l-1.41 1.41"/>
+    </svg>
+    <svg class="theme-icon-moon" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+      <path d="M21 12.79A9 9 0 1 1 11.21 3 7 7 0 0 0 21 12.79z"/>
+    </svg>
+  </button>
+  <div class="launcher-panel theme-menu-panel" role="menu" aria-label="Theme">
+    {%- for choice, label in [('light', 'Light'), ('dark', 'Dark'), ('system', 'System')] %}
+    <button class="launcher-item theme-menu-item{{ ' current' if choice == current }}" type="button" role="menuitemradio" aria-checked="{{ 'true' if choice == current else 'false' }}" data-value="{{ choice }}">{{ label }}</button>
+    {%- endfor %}
+  </div>
+</div>
+{%- endmacro %}

package/templates/jinja/user-menu.html

@@ -0,0 +1,55 @@
+{#- User menu, same markup as recipes/user-menu.html. Goes last in the shell cluster, after the launcher and the theme control.
+
+    {% from "fikar/user-menu.html" import user_menu, user_initials %}
+    {{ user_menu(email=me.email, sign_out_href=sign_out_url, name=me.name, avatar_url=me.avatar_url, account_href="/account") }}
+
+    email           the signed-in person's email. Required
+    sign_out_href   where the Sign out link goes. Required. The address is the host's, so where a person lands stays as it is
+    name            optional full name. With no name the panel shows the email once
+    avatar_url      optional picture. With none, or when it fails to load, the avatar shows initials. data-initials on the trigger always carries them
+    account_href    optional address of Account settings. Leave it out and the row is not rendered, for the page that would link to itself
+    items           optional list of extra rows, each with label and href, rendered after Account settings and before Sign out
+
+    user_initials(name, email) is the rule for the initials: the first letter of the first word of the name and of the last word,
+    or the first letter of the email when there is no name. A single word gives one letter. Words are split on whitespace, the
+    letters are upper case, and non-ASCII letters work. It is also useful on its own when a host needs the initials elsewhere.
+
+    The root carries data-fk-menu, so shell.js handles opening and closing. Leave it out of a host that wires the menu itself. -#}
+{% macro user_initials(name, email) -%}
+{%- set words = (name or '').split() -%}
+{%- if words -%}{{ (words[0][:1] ~ (words[-1][:1] if words | length > 1 else '')) | upper }}
+{%- else -%}{{ (email or '')[:1] | upper }}{%- endif -%}
+{%- endmacro %}
+
+{% macro user_menu(email, sign_out_href, name='', avatar_url='', account_href='', items=none) -%}
+{%- set full_name = (name or '').split() | join(' ') %}
+{%- set initials = user_initials(name, email) %}
+<div class="launcher" data-fk-menu>
+  <button class="user-menu-btn" type="button" aria-haspopup="menu" aria-expanded="false" aria-label="Open account menu" data-initials="{{ initials }}">
+    {%- if avatar_url %}
+    <img class="avatar" src="{{ avatar_url }}" alt="">
+    {%- else %}
+    <span class="avatar" aria-hidden="true">{{ initials }}</span>
+    {%- endif %}
+  </button>
+  <div class="launcher-panel user-menu-panel" role="menu">
+    <div class="user-menu-id">
+      <span class="user-menu-name">{{ full_name or email }}</span>
+      {%- if full_name %}
+      <span class="user-menu-email">{{ email }}</span>
+      {%- endif %}
+    </div>
+    <div class="user-menu-sep" role="separator"></div>
+    {%- if account_href %}
+    <a class="launcher-item user-menu-item" role="menuitem" href="{{ account_href }}">Account settings</a>
+    {%- endif %}
+    {%- for item in items or [] %}
+    <a class="launcher-item user-menu-item" role="menuitem" href="{{ item.href }}">{{ item.label }}</a>
+    {%- endfor %}
+    {%- if account_href or items %}
+    <div class="user-menu-sep" role="separator"></div>
+    {%- endif %}
+    <a class="launcher-item user-menu-item" role="menuitem" href="{{ sign_out_href }}">Sign out</a>
+  </div>
+</div>
+{%- endmacro %}