Lily Design System™ — Nunjucks PickerBar

Link picker (0.3.0). Pass links (and labels.link) to add a link-picker — a home icon opening the page links your app defines — as the leftmost icon. It renders only when both are given.

A single page-header macro that composes five of the Lily *-picker helpers in this catalog — search, theme, locale, text size, and share, in that order — with two catalog-wide defaults pre-wired, so you can call one macro instead of assembling and configuring five.

motion-picker and date-time-picker are not part of the bar: motion has no natural spot next to the other three header preferences, and date-time-picker is a form control, not a header control.

Install

npm install @lilydesignsystem/nunjucks-picker-bar

@lilydesignsystem/nunjucks-search-picker, -theme-picker, -locale-picker, -text-size-picker, and -share-picker install automatically as regular dependencies — pickerBar is a thin wrapper around them, not a reimplementation.

Point your Nunjucks Environment at node_modules so the macro's cross-package imports resolve:

import nunjucks from "nunjucks";
const env = nunjucks.configure(["views", "node_modules"], { autoescape: true });

Usage

{% from "lily-design-system-nunjucks-picker-bar/dist/picker-bar.njk" import pickerBar %}

{{ pickerBar({
  labels: {
    search: "Search this site",
    searchInput: "Search terms",
    searchSubmit: "Search",
    theme: "Theme",
    locale: "Language",
    textSize: "Text size",
    share: "Share"
  },
  themesUrl: "/assets/themes/",
  locales: ["en", "cy", "gd", "ga"],
  shareTargets: [
    { id: "email", label: "Email", href: "mailto:?subject=Check this out&body=https://example.com" }
  ]
}) }}

Then load picker-bar.client.js once and call autoInit():

<script type="module">
  import { autoInit } from "/path/to/picker-bar.client.js";
  autoInit();
</script>

That's a complete, working header row: a site search (a search for foo goes to /?foo), 45 themes, four locales, the seven-step text-size scale, and one share destination plus copy-to-URL if you add shareProps: { copyLabel: "Copy link" }.

Note the share-picker deviation: href in shareTargets is an already-resolved string, not a function — a Nunjucks macro cannot call an arbitrary JS function.

Defaults

• themes defaults to DEFAULT_THEMES — all 45 Lily reference theme slugs, alphabetical, with the 8 United Kingdom / United States government themes moved to their own alphabetical group at the bottom. Pass your own themes array to override.
• sizes defaults to DEFAULT_SIZES — the seven-step scale largest, larger, large, normal, small, smaller, smallest — and the text-size picker starts on normal. Pass your own sizes array (and textSizeProps: { defaultValue: "…" } if you want a different starting point) to override.

Both are exported from the client.js module too:

import { DEFAULT_THEMES, DEFAULT_SIZES } from "@lilydesignsystem/nunjucks-picker-bar";

Passing extra params to one picker

Each wrapped picker takes a *Props object for anything beyond what pickerBar lifts to the top level — persistence, initial value, detection, a *Labels override map, an id:

{{ pickerBar({
  labels: {
    search: "Search this site", searchInput: "Search terms", searchSubmit: "Search",
    theme: "Theme", locale: "Language", textSize: "Text size", share: "Share"
  },
  themesUrl: "/assets/themes/",
  locales: ["en", "cy"],
  searchProps: { action: "/search", placeholder: "Search…" },
  themeProps: { storageKey: "lily-theme", detectFromSystem: true },
  localeProps: { storageKey: "lily-locale", detectFromNavigator: true },
  textSizeProps: { storageKey: "lily-text-size" },
  shareProps: { copyLabel: "Copy link", copiedLabel: "Copied" }
}) }}

search-picker's function-valued options — navigate (default location.assign) and onSearch — cannot pass through a macro, so hand them to the client instead:

autoInit({ searchProps: { navigate: (href) => router.go(href) } });

Unlike the Svelte canonical, pickerBar cannot route a custom glyph to one specific picker (a Nunjucks macro call accepts only one {% call %} block) — compose the five macros directly if you need that.

Styling

pickerBar renders no CSS of its own beyond the picker-bar root wrapper — style each child through its own package's class hooks (search-picker, theme-picker, locale-picker, text-size-picker, share-picker; see each package's own index.md). A typical header layout:

.picker-bar {
  display: flex;
  gap: var(--theme-space-sm, 0.5rem);
  align-items: center;
}

Accessibility

Every accessible name comes from labels — search, searchInput, and searchSubmit name the search picker's button and landmark, field, and ⏎ button; theme, locale, textSize, share the others — and there is no English default, because a set of names this catalog invented is exactly the case the rest of Lily's i18n rule exists for. Each wrapped picker keeps its own WAI-ARIA APG contract unchanged; see that picker's own index.md. As with every helper in this catalog, none of the five is operable until its client.js has run — see each package's own docs/ssr.md.

Full contract

See spec/index.md.

Lily™ and Lily Design System™ are trademarks.