@lilydesignsystem/html-picker-bar 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,110 @@
+import { ThemePickerProps, ThemePicker } from '@lilydesignsystem/html-theme-picker';
+import { LocalePickerProps, LocalePicker } from '@lilydesignsystem/html-locale-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';
+
+/**
+ * `<picker-bar>` — Lily Design System HTML helper.
+ *
+ * See `./spec/index.md` for the canonical contract. This file implements
+ * the custom-element class but does NOT register it. The `index.ts`
+ * barrel registers it on import.
+ *
+ * A thin composition: renders `<theme-picker>`, `<locale-picker>`,
+ * `<text-size-picker>`, and `<share-picker>` — each imported from its
+ * own published package, not vendored — inside one
+ * `<div class="picker-bar {class}">` row. Owns no lifecycle of its
+ * own beyond two catalog-specific defaults (§5.1, §5.2 of the spec).
+ */
+
+/**
+ * All 45 Lily reference theme slugs (see `themes/` at the repo root),
+ * sorted alphabetically except the United Kingdom and United States
+ * government/public-sector themes, which sort last as one alphabetical
+ * group of their own. Mirrors `theme-picker`'s own title-casing of each
+ * slug, so no `theme-labels` override is needed for these to read well.
+ */
+declare const DEFAULT_THEMES: string[];
+/**
+ * The seven-step text-size scale. Each slug title-cases to exactly the
+ * requested label ("largest" → "Largest", …) via `text-size-picker`'s
+ * own default label resolver, so no `size-labels` override is needed
+ * either.
+ */
+declare const DEFAULT_SIZES: string[];
+/** Accessible names for the four pickers. Required — no English default. */
+type PickerBarLabels = {
+    /** Accessible name for the theme picker's button and listbox. */
+    theme: string;
+    /** Accessible name for the locale picker's button and listbox. */
+    locale: string;
+    /** Accessible name for the text-size picker's button and listbox. */
+    textSize: string;
+    /** Accessible name for the share picker's button and list. */
+    share: string;
+};
+/**
+ * Extra per-picker configuration, applied to that picker's element
+ * instance (via property assignment, which each sibling package
+ * reflects onto its own attributes) BEFORE the element is connected —
+ * so persistence, detection, and initial-value props still take
+ * effect on first mount. Applied after `<picker-bar>`'s own defaults,
+ * so anything here overrides them. Excludes the props `<picker-bar>`
+ * already lifts to the top level.
+ */
+type ThemePickerExtra = Partial<Omit<ThemePickerProps, "label" | "themesUrl" | "themes">>;
+type LocalePickerExtra = Partial<Omit<LocalePickerProps, "label" | "locales">>;
+type TextSizePickerExtra = Partial<Omit<TextSizePickerProps, "label" | "sizes">>;
+type SharePickerExtra = Partial<Omit<SharePickerProps, "label" | "targets">>;
+/** Mirrors the observed attributes / properties for typing convenience. */
+type PickerBarProps = {
+    labels: PickerBarLabels;
+    themesUrl: string;
+    themes?: string[];
+    themeProps?: ThemePickerExtra;
+    locales: string[];
+    localeProps?: LocalePickerExtra;
+    sizes?: string[];
+    textSizeProps?: TextSizePickerExtra;
+    shareTargets?: ShareTarget[];
+    shareProps?: SharePickerExtra;
+    class?: string;
+};
+/** Custom-element class implementing `<picker-bar>`. */
+declare class PickerBar extends HTMLElement {
+    #private;
+    static get observedAttributes(): string[];
+    get labels(): PickerBarLabels;
+    set labels(v: PickerBarLabels);
+    get themesUrl(): string;
+    set themesUrl(v: string);
+    get themes(): string[];
+    set themes(v: string[]);
+    get locales(): string[];
+    set locales(v: string[]);
+    get sizes(): string[];
+    set sizes(v: string[]);
+    get shareTargets(): ShareTarget[];
+    set shareTargets(v: ShareTarget[]);
+    get themeProps(): ThemePickerExtra;
+    set themeProps(v: ThemePickerExtra);
+    get localeProps(): LocalePickerExtra;
+    set localeProps(v: LocalePickerExtra);
+    get textSizeProps(): TextSizePickerExtra;
+    set textSizeProps(v: TextSizePickerExtra);
+    get shareProps(): SharePickerExtra;
+    set shareProps(v: SharePickerExtra);
+    /** The rendered `<theme-picker>` instance, once connected. */
+    get themePicker(): ThemePicker | null;
+    /** The rendered `<locale-picker>` instance, once connected. */
+    get localePicker(): LocalePicker | null;
+    /** The rendered `<text-size-picker>` instance, once connected. */
+    get textSizePicker(): TextSizePicker | null;
+    /** The rendered `<share-picker>` instance, once connected. */
+    get sharePicker(): SharePicker | null;
+    connectedCallback(): void;
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+}
+
+export { DEFAULT_SIZES, DEFAULT_THEMES, type LocalePickerExtra, PickerBar, type PickerBarLabels, type PickerBarProps, type SharePickerExtra, type TextSizePickerExtra, type ThemePickerExtra };

package/dist/index.js

@@ -0,0 +1,274 @@
+// lily-design-system-html-picker-bar/picker-bar.ts
+import "@lilydesignsystem/html-theme-picker";
+import "@lilydesignsystem/html-locale-picker";
+import "@lilydesignsystem/html-text-size-picker";
+import "@lilydesignsystem/html-share-picker";
+var DEFAULT_THEMES = [
+  "abyss",
+  "acid",
+  "adobe-spectrum",
+  "aqua",
+  "autumn",
+  "black",
+  "bumblebee",
+  "business",
+  "caramellatte",
+  "cmyk",
+  "coffee",
+  "corporate",
+  "cupcake",
+  "cyberpunk",
+  "dark",
+  "dim",
+  "dracula",
+  "emerald",
+  "fantasy",
+  "forest",
+  "garden",
+  "halloween",
+  "lemonade",
+  "light",
+  "lofi",
+  "luxury",
+  "mozilla-protocol",
+  "night",
+  "nord",
+  "pastel",
+  "retro",
+  "silk",
+  "sunset",
+  "synthwave",
+  "valentine",
+  "winter",
+  "wireframe",
+  "united-kingdom-government-digital-service",
+  "united-kingdom-national-health-service-england-for-patients",
+  "united-kingdom-national-health-service-england-for-practitioners",
+  "united-kingdom-national-health-service-scotland-for-patients",
+  "united-kingdom-national-health-service-scotland-for-practitioners",
+  "united-kingdom-national-health-service-wales-for-patients",
+  "united-kingdom-national-health-service-wales-for-practitioners",
+  "united-states-web-design-system"
+];
+var DEFAULT_SIZES = [
+  "largest",
+  "larger",
+  "large",
+  "normal",
+  "small",
+  "smaller",
+  "smallest"
+];
+var DEFAULT_LABELS = {
+  theme: "",
+  locale: "",
+  textSize: "",
+  share: ""
+};
+var PickerBar = class extends HTMLElement {
+  static get observedAttributes() {
+    return ["themes-url", "themes", "locales", "sizes", "class"];
+  }
+  // Backing storage for property-only members (no honest attribute
+  // encoding — labels/targets carry non-string data, and the *Extra
+  // bags are applied at property-assignment time, not re-derivable
+  // from an attribute).
+  #labels = DEFAULT_LABELS;
+  #themes = DEFAULT_THEMES;
+  #locales = [];
+  #sizes = DEFAULT_SIZES;
+  #shareTargets = [];
+  #themeProps = {};
+  #localeProps = {};
+  #textSizeProps = {};
+  #shareProps = {};
+  // Rendered-DOM references. Null until #render() has run.
+  #rootEl = null;
+  #themePickerEl = null;
+  #localePickerEl = null;
+  #textSizePickerEl = null;
+  #sharePickerEl = null;
+  // ---- Property accessors ----
+  get labels() {
+    return this.#labels;
+  }
+  set labels(v) {
+    this.#labels = v ?? DEFAULT_LABELS;
+    this.#render();
+  }
+  get themesUrl() {
+    return this.getAttribute("themes-url") ?? "";
+  }
+  set themesUrl(v) {
+    this.setAttribute("themes-url", v);
+  }
+  get themes() {
+    return [...this.#themes];
+  }
+  set themes(v) {
+    this.#themes = Array.isArray(v) && v.length > 0 ? v.slice() : DEFAULT_THEMES;
+    const csv = this.#themes.join(",");
+    if (this.getAttribute("themes") !== csv) {
+      this.setAttribute("themes", csv);
+      return;
+    }
+    this.#render();
+  }
+  get locales() {
+    return [...this.#locales];
+  }
+  set locales(v) {
+    this.#locales = Array.isArray(v) ? v.slice() : [];
+    const csv = this.#locales.join(",");
+    if (this.getAttribute("locales") !== csv) {
+      this.setAttribute("locales", csv);
+      return;
+    }
+    this.#render();
+  }
+  get sizes() {
+    return [...this.#sizes];
+  }
+  set sizes(v) {
+    this.#sizes = Array.isArray(v) && v.length > 0 ? v.slice() : DEFAULT_SIZES;
+    const csv = this.#sizes.join(",");
+    if (this.getAttribute("sizes") !== csv) {
+      this.setAttribute("sizes", csv);
+      return;
+    }
+    this.#render();
+  }
+  get shareTargets() {
+    return [...this.#shareTargets];
+  }
+  set shareTargets(v) {
+    this.#shareTargets = Array.isArray(v) ? v.slice() : [];
+    this.#render();
+  }
+  get themeProps() {
+    return this.#themeProps;
+  }
+  set themeProps(v) {
+    this.#themeProps = v ?? {};
+    this.#render();
+  }
+  get localeProps() {
+    return this.#localeProps;
+  }
+  set localeProps(v) {
+    this.#localeProps = v ?? {};
+    this.#render();
+  }
+  get textSizeProps() {
+    return this.#textSizeProps;
+  }
+  set textSizeProps(v) {
+    this.#textSizeProps = v ?? {};
+    this.#render();
+  }
+  get shareProps() {
+    return this.#shareProps;
+  }
+  set shareProps(v) {
+    this.#shareProps = v ?? {};
+    this.#render();
+  }
+  /** The rendered `<theme-picker>` instance, once connected. */
+  get themePicker() {
+    return this.#themePickerEl;
+  }
+  /** The rendered `<locale-picker>` instance, once connected. */
+  get localePicker() {
+    return this.#localePickerEl;
+  }
+  /** The rendered `<text-size-picker>` instance, once connected. */
+  get textSizePicker() {
+    return this.#textSizePickerEl;
+  }
+  /** The rendered `<share-picker>` instance, once connected. */
+  get sharePicker() {
+    return this.#sharePickerEl;
+  }
+  // ---- Lifecycle ----
+  connectedCallback() {
+    const themesAttr = this.getAttribute("themes");
+    if (themesAttr !== null) this.#themes = parseCsv(themesAttr);
+    const localesAttr = this.getAttribute("locales");
+    if (localesAttr !== null) this.#locales = parseCsv(localesAttr);
+    const sizesAttr = this.getAttribute("sizes");
+    if (sizesAttr !== null) this.#sizes = parseCsv(sizesAttr);
+    this.#render();
+  }
+  attributeChangedCallback(name, _old, value) {
+    switch (name) {
+      case "themes":
+        this.#themes = value === null ? DEFAULT_THEMES : parseCsv(value);
+        this.#render();
+        break;
+      case "locales":
+        this.#locales = value === null ? [] : parseCsv(value);
+        this.#render();
+        break;
+      case "sizes":
+        this.#sizes = value === null ? DEFAULT_SIZES : parseCsv(value);
+        this.#render();
+        break;
+      case "themes-url":
+      case "class":
+        this.#render();
+        break;
+      default:
+        break;
+    }
+  }
+  // ---- Rendering ----
+  #render() {
+    if (!this.isConnected) return;
+    const extraClass = this.getAttribute("class") ?? "";
+    const root = document.createElement("div");
+    root.className = `picker-bar ${extraClass}`.trim();
+    const themeEl = document.createElement("theme-picker");
+    themeEl.label = this.#labels.theme;
+    themeEl.themesUrl = this.themesUrl;
+    themeEl.themes = this.#themes;
+    Object.assign(themeEl, this.#themeProps);
+    root.appendChild(themeEl);
+    const localeEl = document.createElement("locale-picker");
+    localeEl.label = this.#labels.locale;
+    localeEl.locales = this.#locales;
+    Object.assign(localeEl, this.#localeProps);
+    root.appendChild(localeEl);
+    const textSizeEl = document.createElement(
+      "text-size-picker"
+    );
+    textSizeEl.label = this.#labels.textSize;
+    textSizeEl.sizes = this.#sizes;
+    textSizeEl.defaultValue = "normal";
+    Object.assign(textSizeEl, this.#textSizeProps);
+    root.appendChild(textSizeEl);
+    const shareEl = document.createElement("share-picker");
+    shareEl.label = this.#labels.share;
+    shareEl.targets = this.#shareTargets;
+    Object.assign(shareEl, this.#shareProps);
+    root.appendChild(shareEl);
+    this.replaceChildren(root);
+    this.#rootEl = root;
+    this.#themePickerEl = themeEl;
+    this.#localePickerEl = localeEl;
+    this.#textSizePickerEl = textSizeEl;
+    this.#sharePickerEl = shareEl;
+  }
+};
+function parseCsv(s) {
+  return s.split(",").map((p) => p.trim()).filter((p) => p.length > 0);
+}
+
+// lily-design-system-html-picker-bar/index.ts
+if (typeof customElements !== "undefined" && !customElements.get("picker-bar")) {
+  customElements.define("picker-bar", PickerBar);
+}
+export {
+  DEFAULT_SIZES,
+  DEFAULT_THEMES,
+  PickerBar
+};

package/index.md

@@ -0,0 +1,149 @@
+# Lily Design System™ — HTML PickerBar
+
+A single page-header custom element, `<picker-bar>`, that composes four
+of the Lily [`*-picker` helpers](../index.md) — theme, locale, text
+size, and share — with two catalog-wide defaults pre-wired, so you can
+drop one element into a header instead of assembling and configuring
+four.
+
+`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-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 = {
+  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 = {
+    theme: "Theme",
+    locale: "Language",
+    textSize: "Text size",
+    share: "Share",
+  };
+</script>
+```
+
+`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.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.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
+(`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/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@lilydesignsystem/html-picker-bar",
+  "version": "0.1.0",
+  "engines": {
+    "node": "=26"
+  },
+  "description": "Lily Design System HTML picker bar: composes theme-picker, locale-picker, 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",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "index.md",
+    "README.md"
+  ],
+  "scripts": {
+    "prepublishOnly": "cd .. && npm run build"
+  },
+  "dependencies": {
+    "@lilydesignsystem/html-theme-picker": "^0.1.0",
+    "@lilydesignsystem/html-locale-picker": "^0.1.0",
+    "@lilydesignsystem/html-text-size-picker": "^0.1.0",
+    "@lilydesignsystem/html-share-picker": "^0.1.0"
+  },
+  "keywords": [
+    "lily",
+    "design",
+    "system",
+    "html",
+    "picker",
+    "picker-bar",
+    "theme",
+    "locale",
+    "text-size",
+    "share"
+  ],
+  "author": "Joel Parker Henderson <joel@joelparkerhenderson.com>",
+  "license": "MIT OR Apache-2.0 OR GPL-2.0-only OR GPL-3.0-only OR BSD-3-Clause",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LilyDesignSystem/lily-design-system-html-helpers.git",
+    "directory": "lily-design-system-html-picker-bar"
+  },
+  "homepage": "https://lilydesignsystem.com/",
+  "bugs": {
+    "url": "https://github.com/LilyDesignSystem/lily-design-system/issues"
+  }
+}