@lilydesignsystem/html-picker-bar 0.4.0 → 0.5.0

package/README.md

@@ -0,0 +1,167 @@
+# Lily Design System™ — HTML 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).** Set `labels.timeZone` and `timeZoneProps = { locale: "fr" }` (plus any `<time-zone-picker>` property, e.g. `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 custom element, `<picker-bar>`, that composes five
+of the Lily [`*-picker` helpers](../index.md) — search, theme, locale,
+text size, and share, in that order — with two catalog-wide defaults
+pre-wired, so you can drop one element into a header 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/html-picker-bar
+```
+
+`@lilydesignsystem/html-search-picker`, `-theme-picker`,
+`-locale-picker`, `-text-size-picker`, and `-share-picker` install automatically as
+regular dependencies — `<picker-bar>` is a thin wrapper around them,
+not a reimplementation.
+
+## Usage
+
+```js
+import "@lilydesignsystem/html-picker-bar";
+
+const bar = document.createElement("picker-bar");
+bar.labels = {
+  search: "Search this site",
+  searchInput: "Search terms",
+  searchSubmit: "Search",
+  theme: "Theme",
+  locale: "Language",
+  textSize: "Text size",
+  share: "Share",
+};
+bar.themesUrl = "/assets/themes/";
+bar.locales = ["en", "cy", "gd", "ga"];
+bar.shareTargets = [
+  {
+    id: "email",
+    label: "Email",
+    href: (url, title) => `mailto:?subject=${title}&body=${url}`,
+  },
+];
+document.querySelector("header").appendChild(bar);
+```
+
+Or in markup, for the parts that fit plain attributes:
+
+```html
+<script type="module" src="/node_modules/lily-design-system-html-picker-bar/dist/index.js"></script>
+<picker-bar themes-url="/assets/themes/" locales="en,cy,gd,ga"></picker-bar>
+<script type="module">
+  document.querySelector("picker-bar").labels = {
+    search: "Search this site",
+    searchInput: "Search terms",
+    searchSubmit: "Search",
+    theme: "Theme",
+    locale: "Language",
+    textSize: "Text size",
+    share: "Share",
+  };
+</script>
+```
+
+Search sends a query for `foo` to `/?foo` by default. `labels` carries
+seven names: three for search (`search` names its button and search
+landmark, `searchInput` the field, `searchSubmit` the `⏎` button) and
+one for each other picker.
+
+`labels` has to be set as a JS property (no honest attribute encoding
+exists for an object), same as `shareTargets` — see
+`<date-time-picker>`'s `labels` and `<share-picker>`'s `targets` for the
+same pattern elsewhere in this catalog.
+
+## 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. Set your own `themes` attribute (comma-separated) or
+  `.themes` property (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`. Set your
+  own `sizes` to override (and `textSizeProps = { defaultValue: "…" }`
+  for a different starting point).
+
+Both are exported as named constants:
+
+```js
+import { DEFAULT_THEMES, DEFAULT_SIZES } from "@lilydesignsystem/html-picker-bar";
+```
+
+## Passing extra configuration to one picker
+
+Each wrapped picker takes a `*Props` bag — a property, not an
+attribute — for anything beyond what `<picker-bar>` lifts to the top
+level: persistence, initial value, detection, a `*Labels` override map.
+
+```js
+bar.searchProps = { action: "/search", placeholder: "Search…", navigate: (href) => router.push(href) };
+bar.themeProps = { storageKey: "lily-theme", detectFromSystem: true };
+bar.localeProps = { storageKey: "lily-locale", detectFromNavigator: true };
+bar.textSizeProps = { storageKey: "lily-text-size" };
+bar.shareProps = { copyLabel: "Copy link", copiedLabel: "Copied" };
+```
+
+Set these **before** appending `bar` to the document — they apply to
+the wrapped picker's element instance before it connects, so
+persistence and initial-value resolution see them on first mount, the
+same as if you had configured that picker directly.
+
+## Reading a wrapped picker directly
+
+After `<picker-bar>` has rendered (i.e. once it's connected to the
+document), each wrapped element is available as a read-only property:
+
+```js
+bar.searchPicker; // the <search-picker> instance
+bar.themePicker; // the <theme-picker> instance
+bar.localePicker; // the <locale-picker> instance
+bar.textSizePicker; // the <text-size-picker> instance
+bar.sharePicker; // the <share-picker> instance
+```
+
+Useful for attaching a `themechange` listener, reading `.value`, or any
+other post-mount interaction — the elements are real, unmodified
+instances of their own packages.
+
+## Styling
+
+`<picker-bar>` renders no CSS of its own beyond the `picker-bar` root
+wrapper class — 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` — 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`.
+
+## Full contract
+
+See [`spec/index.md`](./spec/index.md).
+
+---
+
+Lily™ and Lily Design System™ are trademarks.

package/dist/index.d.ts

@@ -2,6 +2,7 @@ import { LinkItem, LinkPickerProps, LinkPicker } from '@lilydesignsystem/html-li
 import { SearchPickerProps, SearchPicker } from '@lilydesignsystem/html-search-picker';
 import { ThemePickerProps, ThemePicker } from '@lilydesignsystem/html-theme-picker';
 import { LocalePickerProps, LocalePicker } from '@lilydesignsystem/html-locale-picker';
+import { TimeZonePickerProps, TimeZonePicker } from '@lilydesignsystem/html-time-zone-picker';
 import { TextSizePickerProps, TextSizePicker } from '@lilydesignsystem/html-text-size-picker';
 import { ShareTarget, SharePickerProps, SharePicker } from '@lilydesignsystem/html-share-picker';
 export { ShareTarget } from '@lilydesignsystem/html-share-picker';
@@ -55,6 +56,11 @@ type PickerBarLabels = {
     locale: string;
     /** Accessible name for the text-size picker's button and listbox. */
     textSize: string;
+    /**
+     * Accessible name for the time-zone picker's button and listbox. Needed only when
+     * `timeZoneProps.locale` is supplied; the time-zone picker renders only when both are present.
+     */
+    timeZone?: string;
     /** Accessible name for the share picker's button and list. */
     share: string;
 };
@@ -71,6 +77,7 @@ type LinkPickerExtra = Partial<Omit<LinkPickerProps, "label" | "links">>;
 type SearchPickerExtra = Partial<Omit<SearchPickerProps, "label" | "inputLabel" | "submitLabel">>;
 type ThemePickerExtra = Partial<Omit<ThemePickerProps, "label" | "themesUrl" | "themes">>;
 type LocalePickerExtra = Partial<Omit<LocalePickerProps, "label" | "locales">>;
+type TimeZonePickerExtra = Partial<Omit<TimeZonePickerProps, "label">>;
 type TextSizePickerExtra = Partial<Omit<TextSizePickerProps, "label" | "sizes">>;
 type SharePickerExtra = Partial<Omit<SharePickerProps, "label" | "targets">>;
 /** Mirrors the observed attributes / properties for typing convenience. */
@@ -85,6 +92,8 @@ type PickerBarProps = {
     themeProps?: ThemePickerExtra;
     locales: string[];
     localeProps?: LocalePickerExtra;
+    /** `locale` (the language that names and sorts the zones) is required for the time-zone picker, after the locale picker, to render. */
+    timeZoneProps?: TimeZonePickerExtra;
     sizes?: string[];
     textSizeProps?: TextSizePickerExtra;
     shareTargets?: ShareTarget[];
@@ -117,6 +126,8 @@ declare class PickerBar extends HTMLElement {
     set themeProps(v: ThemePickerExtra);
     get localeProps(): LocalePickerExtra;
     set localeProps(v: LocalePickerExtra);
+    get timeZoneProps(): TimeZonePickerExtra;
+    set timeZoneProps(v: TimeZonePickerExtra);
     get textSizeProps(): TextSizePickerExtra;
     set textSizeProps(v: TextSizePickerExtra);
     get shareProps(): SharePickerExtra;
@@ -129,6 +140,8 @@ declare class PickerBar extends HTMLElement {
     get themePicker(): ThemePicker | null;
     /** The rendered `<locale-picker>` instance, once connected. */
     get localePicker(): LocalePicker | null;
+    /** The rendered `<time-zone-picker>` instance, once connected (null without a label and locale). */
+    get timeZonePicker(): TimeZonePicker | null;
     /** The rendered `<text-size-picker>` instance, once connected. */
     get textSizePicker(): TextSizePicker | null;
     /** The rendered `<share-picker>` instance, once connected. */
@@ -137,4 +150,5 @@ declare class PickerBar extends HTMLElement {
     attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
 }
 
-export { DEFAULT_SIZES, DEFAULT_THEMES, type LocalePickerExtra, PickerBar, type PickerBarLabels, type PickerBarProps, type SearchPickerExtra, type SharePickerExtra, type TextSizePickerExtra, type ThemePickerExtra };
+export { DEFAULT_SIZES, DEFAULT_THEMES, PickerBar };
+export type { LocalePickerExtra, PickerBarLabels, PickerBarProps, SearchPickerExtra, SharePickerExtra, TextSizePickerExtra, ThemePickerExtra, TimeZonePickerExtra };

package/dist/index.js

@@ -3,6 +3,7 @@ import "@lilydesignsystem/html-link-picker";
 import "@lilydesignsystem/html-search-picker";
 import "@lilydesignsystem/html-theme-picker";
 import "@lilydesignsystem/html-locale-picker";
+import "@lilydesignsystem/html-time-zone-picker";
 import "@lilydesignsystem/html-text-size-picker";
 import "@lilydesignsystem/html-share-picker";
 var DEFAULT_THEMES = [
@@ -100,6 +101,7 @@ var PickerBar = class extends HTMLElement {
   #searchProps = {};
   #themeProps = {};
   #localeProps = {};
+  #timeZoneProps = {};
   #textSizeProps = {};
   #shareProps = {};
   // Rendered-DOM references. Null until #render() has run.
@@ -108,6 +110,7 @@ var PickerBar = class extends HTMLElement {
   #searchPickerEl = null;
   #themePickerEl = null;
   #localePickerEl = null;
+  #timeZonePickerEl = null;
   #textSizePickerEl = null;
   #sharePickerEl = null;
   // ---- Property accessors ----
@@ -202,6 +205,13 @@ var PickerBar = class extends HTMLElement {
     this.#localeProps = v ?? {};
     this.#render();
   }
+  get timeZoneProps() {
+    return this.#timeZoneProps;
+  }
+  set timeZoneProps(v) {
+    this.#timeZoneProps = v ?? {};
+    this.#render();
+  }
   get textSizeProps() {
     return this.#textSizeProps;
   }
@@ -232,6 +242,10 @@ var PickerBar = class extends HTMLElement {
   get localePicker() {
     return this.#localePickerEl;
   }
+  /** The rendered `<time-zone-picker>` instance, once connected (null without a label and locale). */
+  get timeZonePicker() {
+    return this.#timeZonePickerEl;
+  }
   /** The rendered `<text-size-picker>` instance, once connected. */
   get textSizePicker() {
     return this.#textSizePickerEl;
@@ -304,6 +318,14 @@ var PickerBar = class extends HTMLElement {
     localeEl.locales = this.#locales;
     Object.assign(localeEl, this.#localeProps);
     root.appendChild(localeEl);
+    let timeZoneEl = null;
+    if (this.#labels.timeZone && this.#timeZoneProps.locale) {
+      timeZoneEl = document.createElement("time-zone-picker");
+      timeZoneEl.locale = this.#timeZoneProps.locale;
+      Object.assign(timeZoneEl, this.#timeZoneProps);
+      timeZoneEl.label = this.#labels.timeZone;
+      root.appendChild(timeZoneEl);
+    }
     const textSizeEl = document.createElement(
       "text-size-picker"
     );
@@ -322,6 +344,7 @@ var PickerBar = class extends HTMLElement {
     this.#searchPickerEl = searchEl;
     this.#themePickerEl = themeEl;
     this.#localePickerEl = localeEl;
+    this.#timeZonePickerEl = timeZoneEl;
     this.#textSizePickerEl = textSizeEl;
     this.#sharePickerEl = shareEl;
   }

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).** Set `labels.timeZone` and `timeZoneProps = { locale: "fr" }` (plus any `<time-zone-picker>` property, e.g. `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 custom element, `<picker-bar>`, that composes five
 of the Lily [`*-picker` helpers](../index.md) — search, theme, locale,
 text size, and share, in that order — with two catalog-wide defaults

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@lilydesignsystem/html-picker-bar",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "engines": {
-    "node": "=26"
+    "node": ">=26"
   },
-  "description": "Lily Design System HTML 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 HTML 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",
@@ -32,13 +32,14 @@
     "@lilydesignsystem/html-theme-picker": "^0.2.0",
     "@lilydesignsystem/html-locale-picker": "^0.2.0",
     "@lilydesignsystem/html-text-size-picker": "^0.2.0",
+    "@lilydesignsystem/html-time-zone-picker": "^0.1.0",
     "@lilydesignsystem/html-share-picker": "^0.2.0"
   },
   "devDependencies": {
     "jsdom": "^30.1.1",
-    "tsup": "^8.5.1",
+    "tsup": "^9.0.0",
     "typescript": "^5.9.3",
-    "vitest": "^5.0.3"
+    "vitest": "^5.0.4"
   },
   "keywords": [
     "lily",