@lilydesignsystem/nunjucks-picker-bar 0.4.0 → 0.5.0

package/README.md

@@ -0,0 +1,166 @@
+# 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.
+
+> **Time zone picker (0.5.0).** Pass `labels.timeZone` and `timeZoneProps: { locale, options }`, where `options = timeZoneOptions({ locale })` from `@lilydesignsystem/nunjucks-time-zone-picker` is built where the page is built (and `names` there for CLDR names) to add a `time-zone-picker` — time zones by UTC offset with their full names — right after the locale picker. It renders only when both the label and the locale are given. To name the text sizes in the reader's language pass `sizeLabels` through the text-size props (`textSizeLabels(pack)` / `LocaleTranslations.TextSizeLabels(locale)` from the locale-translations package).
+
+A single page-header macro that composes five of the Lily
+[`*-picker` helpers](../index.md) 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
+
+```sh
+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:
+
+```js
+import nunjucks from "nunjucks";
+const env = nunjucks.configure(["views", "node_modules"], { autoescape: true });
+```
+
+## Usage
+
+```njk
+{% 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()`:
+
+```html
+<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](../lily-design-system-nunjucks-share-picker/index.md):
+`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:
+
+```js
+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`:
+
+```njk
+{{ 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:
+
+```js
+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:
+
+```css
+.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`](./spec/index.md).
+
+---
+
+Lily™ and Lily Design System™ are trademarks.

package/dist/index.d.ts

@@ -8,6 +8,7 @@ import { initLocalePicker } from '@lilydesignsystem/nunjucks-locale-picker';
 export { autoInit as autoInitLocalePicker } from '@lilydesignsystem/nunjucks-locale-picker';
 import { initTextSizePicker } from '@lilydesignsystem/nunjucks-text-size-picker';
 export { autoInit as autoInitTextSizePicker } from '@lilydesignsystem/nunjucks-text-size-picker';
+import { initTimeZonePicker } from '@lilydesignsystem/nunjucks-time-zone-picker';
 import { initSharePicker } from '@lilydesignsystem/nunjucks-share-picker';
 export { autoInit as autoInitSharePicker } from '@lilydesignsystem/nunjucks-share-picker';
 
@@ -115,7 +116,7 @@ const DEFAULT_SIZES = [
  * rendered one.
  *
  * @param {HTMLElement} root
- * @param {{linkProps?: object, searchProps?: object, themeProps?: object, localeProps?: object, textSizeProps?: object, shareProps?: object}=} opts
+ * @param {{linkProps?: object, searchProps?: object, themeProps?: object, localeProps?: object, timeZoneProps?: object, textSizeProps?: object, shareProps?: object}=} opts
  */
 function initPickerBar(root, opts = {}) {
   if (!root) {
@@ -124,6 +125,7 @@ function initPickerBar(root, opts = {}) {
       search: null,
       theme: null,
       locale: null,
+      timeZone: null,
       textSize: null,
       share: null,
     };
@@ -133,6 +135,7 @@ function initPickerBar(root, opts = {}) {
     searchProps = {},
     themeProps = {},
     localeProps = {},
+    timeZoneProps = {},
     textSizeProps = {},
     shareProps = {},
   } = opts;
@@ -141,6 +144,7 @@ function initPickerBar(root, opts = {}) {
   const searchRoot = root.querySelector("[data-lily-search-picker-root]");
   const themeRoot = root.querySelector("[data-lily-theme-picker-root]");
   const localeRoot = root.querySelector("[data-lily-locale-picker-root]");
+  const timeZoneRoot = root.querySelector("[data-lily-time-zone-picker-root]");
   const textSizeRoot = root.querySelector(
     "[data-lily-text-size-picker-root]",
   );
@@ -151,6 +155,7 @@ function initPickerBar(root, opts = {}) {
     search: searchRoot ? initSearchPicker(searchRoot, searchProps) : null,
     theme: themeRoot ? initThemePicker(themeRoot, themeProps) : null,
     locale: localeRoot ? initLocalePicker(localeRoot, localeProps) : null,
+    timeZone: timeZoneRoot ? initTimeZonePicker(timeZoneRoot, timeZoneProps) : null,
     textSize: textSizeRoot
       ? initTextSizePicker(textSizeRoot, textSizeProps)
       : null,
@@ -161,7 +166,7 @@ function initPickerBar(root, opts = {}) {
 /**
  * Find every `[data-lily-picker-bar-root]` and wire it.
  *
- * @param {{linkProps?: object, searchProps?: object, themeProps?: object, localeProps?: object, textSizeProps?: object, shareProps?: object}=} opts
+ * @param {{linkProps?: object, searchProps?: object, themeProps?: object, localeProps?: object, timeZoneProps?: object, textSizeProps?: object, shareProps?: object}=} opts
  * @returns {Array<ReturnType<typeof initPickerBar>>}
  */
 function autoInit(opts = {}) {

package/dist/index.js

@@ -19,6 +19,10 @@ import {
   initTextSizePicker,
   autoInit as autoInitTextSizePicker
 } from "@lilydesignsystem/nunjucks-text-size-picker";
+import {
+  initTimeZonePicker,
+  autoInit as autoInitTimeZonePicker
+} from "@lilydesignsystem/nunjucks-time-zone-picker";
 import {
   initSharePicker,
   autoInit as autoInitSharePicker
@@ -98,6 +102,7 @@ function initPickerBar(root, opts = {}) {
       search: null,
       theme: null,
       locale: null,
+      timeZone: null,
       textSize: null,
       share: null
     };
@@ -107,6 +112,7 @@ function initPickerBar(root, opts = {}) {
     searchProps = {},
     themeProps = {},
     localeProps = {},
+    timeZoneProps = {},
     textSizeProps = {},
     shareProps = {}
   } = opts;
@@ -114,6 +120,7 @@ function initPickerBar(root, opts = {}) {
   const searchRoot = root.querySelector("[data-lily-search-picker-root]");
   const themeRoot = root.querySelector("[data-lily-theme-picker-root]");
   const localeRoot = root.querySelector("[data-lily-locale-picker-root]");
+  const timeZoneRoot = root.querySelector("[data-lily-time-zone-picker-root]");
   const textSizeRoot = root.querySelector(
     "[data-lily-text-size-picker-root]"
   );
@@ -123,6 +130,7 @@ function initPickerBar(root, opts = {}) {
     search: searchRoot ? initSearchPicker(searchRoot, searchProps) : null,
     theme: themeRoot ? initThemePicker(themeRoot, themeProps) : null,
     locale: localeRoot ? initLocalePicker(localeRoot, localeProps) : null,
+    timeZone: timeZoneRoot ? initTimeZonePicker(timeZoneRoot, timeZoneProps) : null,
     textSize: textSizeRoot ? initTextSizePicker(textSizeRoot, textSizeProps) : null,
     share: shareRoot ? initSharePicker(shareRoot, shareProps) : null
   };

package/dist/picker-bar.njk

@@ -30,6 +30,7 @@
 {% from "lily-design-system-nunjucks-theme-picker/dist/theme-picker.njk" import themePicker %}
 {% from "lily-design-system-nunjucks-locale-picker/dist/locale-picker.njk" import localePicker %}
 {% from "lily-design-system-nunjucks-text-size-picker/dist/text-size-picker.njk" import textSizePicker %}
+{% from "lily-design-system-nunjucks-time-zone-picker/dist/time-zone-picker.njk" import timeZonePicker %}
 {% from "lily-design-system-nunjucks-share-picker/dist/share-picker.njk" import sharePicker %}
 {#
   All 57 Lily reference theme slugs (see `themes/` at the repo root),
@@ -73,7 +74,7 @@
 {#
   Params (single `opts` object):
     labels        — object, required: { link?, search, searchInput,
-                    searchSubmit, theme, locale, textSize, share }.
+                    searchSubmit, theme, locale, timeZone?, textSize, share }.
                     `link` names the link picker's button and list and is
                     needed only when `links` is supplied.
                     The seven accessible names: `search` names the
@@ -95,6 +96,11 @@
                     no catalog default exists.
     themes        — array<string>. Defaults to DEFAULT_THEMES (above).
     sizes         — array<string>. Defaults to DEFAULT_SIZES (above).
+    timeZoneProps — object. The time-zone picker, rendered after the locale picker only when this has `locale`
+                    and `options` AND `labels.timeZone` is set. `options` is built where the page is built with
+                    `timeZoneOptions({ locale, zones?, date?, labelFor?, names? })` from
+                    @lilydesignsystem/nunjucks-time-zone-picker (a macro cannot call `Intl`); the rest are
+                    time-zone-picker opts (date, value, defaultValue, storageKey, name, id, classes, attributes).
     shareTargets  — array<object>. Forwarded to share-picker's `targets`
                     (default []). See share-picker.njk for the object
                     shape — `href` is an already-resolved string, not a
@@ -148,6 +154,7 @@
 {%- set searchProps = opts.searchProps | default({}) -%}
 {%- set themeProps = opts.themeProps | default({}) -%}
 {%- set localeProps = opts.localeProps | default({}) -%}
+{%- set timeZoneProps = opts.timeZoneProps | default({}) -%}
 {%- set textSizeProps = opts.textSizeProps | default({}) -%}
 {%- set shareProps = opts.shareProps | default({}) -%}
 <div
@@ -206,6 +213,21 @@
   classes: localeProps.classes,
   attributes: localeProps.attributes
 }) }}
+{%- if opts.labels.timeZone and timeZoneProps.locale and timeZoneProps.options %}
+{{ timeZonePicker({
+  label: opts.labels.timeZone,
+  locale: timeZoneProps.locale,
+  options: timeZoneProps.options,
+  date: timeZoneProps.date,
+  value: timeZoneProps.value,
+  defaultValue: timeZoneProps.defaultValue,
+  storageKey: timeZoneProps.storageKey,
+  name: timeZoneProps.name,
+  id: timeZoneProps.id,
+  classes: timeZoneProps.classes,
+  attributes: timeZoneProps.attributes
+}) }}
+{%- endif %}
 {{ textSizePicker({
   label: opts.labels.textSize,
   sizes: sizes,

package/index.md

@@ -2,6 +2,8 @@
 
 > **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.
 
+> **Time zone picker (0.5.0).** Pass `labels.timeZone` and `timeZoneProps: { locale, options }`, where `options = timeZoneOptions({ locale })` from `@lilydesignsystem/nunjucks-time-zone-picker` is built where the page is built (and `names` there for CLDR names) to add a `time-zone-picker` — time zones by UTC offset with their full names — right after the locale picker. It renders only when both the label and the locale are given. To name the text sizes in the reader's language pass `sizeLabels` through the text-size props (`textSizeLabels(pack)` / `LocaleTranslations.TextSizeLabels(locale)` from the locale-translations package).
+
 A single page-header macro that composes five of the Lily
 [`*-picker` helpers](../index.md) in this catalog — search, theme,
 locale, text size, and share, in that order — with two catalog-wide

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@lilydesignsystem/nunjucks-picker-bar",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "engines": {
-    "node": "=26"
+    "node": ">=26"
   },
-  "description": "Lily Design System Nunjucks picker bar: composes link-picker (optional), search-picker, theme-picker, locale-picker, text-size-picker, and share-picker into one page-header row. Headless, SSR-safe, no CSS.",
+  "description": "Lily Design System Nunjucks picker bar: composes link-picker (optional), search-picker, theme-picker, locale-picker, time-zone-picker (optional), text-size-picker, and share-picker into one page-header row. Headless, SSR-safe, no CSS.",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
@@ -33,14 +33,15 @@
     "@lilydesignsystem/nunjucks-theme-picker": "^0.2.0",
     "@lilydesignsystem/nunjucks-locale-picker": "^0.2.0",
     "@lilydesignsystem/nunjucks-text-size-picker": "^0.2.0",
+    "@lilydesignsystem/nunjucks-time-zone-picker": "^0.1.0",
     "@lilydesignsystem/nunjucks-share-picker": "^0.2.0"
   },
   "devDependencies": {
     "jsdom": "^30.1.1",
     "nunjucks": "^3.2.4",
-    "tsup": "^8.5.1",
+    "tsup": "^9.0.0",
     "typescript": "^5.9.3",
-    "vitest": "^5.0.3"
+    "vitest": "^5.0.4"
   },
   "keywords": [
     "lily",