@syware/jlib 0.3.0 → 0.5.0

package/dist/lib/time.js

@@ -0,0 +1,64 @@
+// src/lib/time.ts
+var SECOND_MS = 1e3;
+var MINUTES_PER_HOUR = 60;
+var HOURS_PER_DAY = 24;
+var MINUTE_S = 60;
+var HOUR_S = 3600;
+var DAY_S = HOURS_PER_DAY * HOUR_S;
+var NOW_UNDER_S = 45;
+var MINUTES_UNDER_S = 2700;
+var HOURS_UNDER_S = 22 * HOUR_S;
+var DAYS_UNDER_S = 7 * DAY_S;
+/** A number of one unit, as the language writes it short: "33 secs", "3 min", "2 Std.". */
+var unitText = (value, unit, locale) => new Intl.NumberFormat(locale, {
+	maximumFractionDigits: 0,
+	style: "unit",
+	unit,
+	unitDisplay: "short"
+}).format(value);
+/** Two units side by side, the second left out at zero: "2 hrs 10 mins", "3 days". */
+function pair(first, second, locale) {
+	const parts = [unitText(first[0], first[1], locale)];
+	if (second[0] > 0) parts.push(unitText(second[0], second[1], locale));
+	return new Intl.ListFormat(locale, {
+		style: "narrow",
+		type: "unit"
+	}).format(parts);
+}
+/**
+* A duration in the units that read best: "< 1 sec" under a second (never "0.0 s"), then seconds, minutes, hours
+* and minutes, days and hours.
+*/
+function formatDuration(milliseconds, locale) {
+	const seconds = Math.max(0, milliseconds) / SECOND_MS;
+	if (seconds < 1) return `< ${unitText(1, "second", locale)}`;
+	if (seconds < MINUTE_S) return unitText(Math.round(seconds), "second", locale);
+	if (seconds < HOUR_S) return unitText(Math.round(seconds / MINUTE_S), "minute", locale);
+	if (seconds < DAY_S) {
+		const minutes = Math.round(seconds / MINUTE_S);
+		return pair([Math.floor(minutes / MINUTES_PER_HOUR), "hour"], [minutes % MINUTES_PER_HOUR, "minute"], locale);
+	}
+	const hours = Math.round(seconds / HOUR_S);
+	return pair([Math.floor(hours / HOURS_PER_DAY), "day"], [hours % HOURS_PER_DAY, "hour"], locale);
+}
+/**
+* When something happened, from `now`: "now", "5 minutes ago", "3 hours ago", "yesterday" within a week, then the
+* date ("12 Mar", with the year when it is not this year's). Times to come read the same way: "in 5 minutes".
+*/
+function formatRelativeTime(date, now, locale) {
+	const then = new Date(date);
+	const seconds = (then.getTime() - new Date(now).getTime()) / SECOND_MS;
+	const distance = Math.abs(seconds);
+	const relative = new Intl.RelativeTimeFormat(locale, { numeric: "auto" });
+	if (distance < NOW_UNDER_S) return relative.format(0, "second");
+	if (distance < MINUTES_UNDER_S) return relative.format(Math.round(seconds / MINUTE_S), "minute");
+	if (distance < HOURS_UNDER_S) return relative.format(Math.round(seconds / HOUR_S), "hour");
+	if (distance < DAYS_UNDER_S) return relative.format(Math.round(seconds / DAY_S), "day");
+	const sameYear = then.getFullYear() === new Date(now).getFullYear();
+	return new Intl.DateTimeFormat(locale, {
+		day: "numeric",
+		month: "short",
+		...sameYear ? {} : { year: "numeric" }
+	}).format(then);
+}
+export { formatDuration, formatRelativeTime };

package/dist/lib/tokens.d.ts

@@ -1,5 +1,6 @@
 /**
  * Gives the document the design tokens, once. They live in the `jlib` cascade layer, so the page overrides any of
- * them with a plain rule: `:root { --jl-accent: #7c3aed; }`.
+ * them with a plain rule: `:root { --jl-accent: #7c3aed; }`. Where the document takes no constructed stylesheet, a
+ * style element in its head holds them instead.
  */
 export declare function adoptTokens(): void;

package/dist/lib/tokens.js

@@ -1,15 +1,24 @@
 import { TOKEN_STYLES } from "../styles/shared.js";
 // src/lib/tokens.ts
-var adopted = { sheet: null };
+var adopted = { done: false };
+/** Whether the document takes constructed stylesheets: jsdom, which runs many apps' unit tests, does not. */
+var takesSheets = () => typeof CSSStyleSheet !== "undefined" && typeof CSSStyleSheet.prototype.replaceSync === "function" && Array.isArray(document.adoptedStyleSheets);
 /**
 * Gives the document the design tokens, once. They live in the `jlib` cascade layer, so the page overrides any of
-* them with a plain rule: `:root { --jl-accent: #7c3aed; }`.
+* them with a plain rule: `:root { --jl-accent: #7c3aed; }`. Where the document takes no constructed stylesheet, a
+* style element in its head holds them instead.
 */
 function adoptTokens() {
-	if (adopted.sheet !== null || typeof document === "undefined") return;
+	if (adopted.done || typeof document === "undefined") return;
+	adopted.done = true;
+	if (!takesSheets()) {
+		const style = document.createElement("style");
+		style.textContent = TOKEN_STYLES;
+		document.head.append(style);
+		return;
+	}
 	const sheet = new CSSStyleSheet();
 	sheet.replaceSync(TOKEN_STYLES);
 	document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];
-	adopted.sheet = sheet;
 }
 export { adoptTokens };

package/dist/molecules/jl-account-button.css_raw.js

@@ -0,0 +1,3 @@
+// src/molecules/jl-account-button.css?raw
+var jl_account_button_default = ":host {\n  display: block;\n}\n\n.base {\n  display: flex;\n  width: 100%;\n  padding: 6px 8px;\n  border: 0;\n  border-radius: var(--jl-radius-sm);\n  background: transparent;\n  color: var(--jl-text);\n  text-align: left;\n  text-decoration: none;\n  cursor: pointer;\n  transition: background var(--jl-fast) var(--jl-ease);\n}\n\n.base:hover {\n  background: var(--jl-surface-2);\n}\n\n.content {\n  display: flex;\n  flex: 1;\n  align-items: center;\n  gap: 10px;\n  min-width: 0;\n}\n\njl-avatar {\n  flex: none;\n}\n\n.text {\n  display: grid;\n  min-width: 0;\n  line-height: 1.3;\n}\n\n.name,\n.description {\n  overflow: hidden;\n  text-overflow: ellipsis;\n  white-space: nowrap;\n}\n\n.name {\n  font-size: var(--jl-font-sm);\n  font-weight: 650;\n}\n\n.description {\n  color: var(--jl-muted);\n  font-size: var(--jl-font-xs);\n}\n\n/* The avatar alone, round. */\n:host([compact]) {\n  display: inline-block;\n}\n\n:host([compact]) .base {\n  width: auto;\n  padding: 2px;\n  border-radius: var(--jl-radius-pill);\n}\n\n:host([compact]) .text {\n  display: none;\n}\n";
+export { jl_account_button_default as default };

package/dist/molecules/jl-account-button.d.ts

@@ -0,0 +1,46 @@
+import { JlElement } from '../base/jl-element';
+/**
+ * The person signed in, where the frame of an app shows them (the foot of the side nav, a phone's top bar): their
+ * avatar, their name, and a line under it such as their role. With an `href` it is a link to their account, else a
+ * button that fires `press` (to open a menu). `compact` keeps the avatar alone, the name as its tooltip.
+ */
+export declare class JlAccountButton extends JlElement {
+    static readonly selector = "jl-account-button";
+    readonly events: Readonly<import("@jadis/core").UseEventsHandler<{
+        press: undefined;
+    }>>;
+    readonly name: Readonly<Readonly<{
+        get(): string;
+        set(setter: string | ((prevState: string) => string)): void;
+    }>>;
+    /** The line under the name: their role, their company. */
+    readonly description: Readonly<Readonly<{
+        get(): string;
+        set(setter: string | ((prevState: string) => string)): void;
+    }>>;
+    /** Their picture; their initials without it. */
+    readonly src: Readonly<Readonly<{
+        get(): string;
+        set(setter: string | ((prevState: string) => string)): void;
+    }>>;
+    /** Their account's address: the button becomes a link. */
+    readonly href: Readonly<Readonly<{
+        get(): string;
+        set(setter: string | ((prevState: string) => string)): void;
+    }>>;
+    /** The avatar alone. */
+    readonly compact: Readonly<Readonly<{
+        get(): boolean;
+        set(setter: boolean | ((prevState: boolean) => boolean)): void;
+    }>>;
+    private readonly _refs;
+    focus(options?: FocusOptions): void;
+    templateHtml(): Node;
+    templateCss(): string;
+    onConnect(): void;
+    private control;
+    /** Moves the content into the link or back into the button. */
+    private renderLink;
+    /** Its name for screen readers and its tooltip: the name, then the line under it. */
+    private renderLabel;
+}

package/dist/molecules/jl-account-button.js

@@ -0,0 +1,97 @@
+import { BASE_STYLES } from "../styles/shared.js";
+import { JlElement } from "../base/jl-element.js";
+import { setOrRemove } from "../lib/dom.js";
+import { JlAvatar } from "../atoms/jl-avatar.js";
+import jl_account_button_default from "./jl-account-button.css_raw.js";
+import { css } from "@jadis/core";
+import { Fragment, jsx, jsxs } from "@jadis/core/jsx-runtime";
+// src/molecules/jl-account-button.tsx
+/**
+* The person signed in, where the frame of an app shows them (the foot of the side nav, a phone's top bar): their
+* avatar, their name, and a line under it such as their role. With an `href` it is a link to their account, else a
+* button that fires `press` (to open a menu). `compact` keeps the avatar alone, the name as its tooltip.
+*/
+var JlAccountButton = class extends JlElement {
+	static selector = "jl-account-button";
+	events = this.useEvents();
+	name = this.useChange("", (value) => {
+		this._refs.avatar.name.set(value);
+		this._refs.name.textContent = value;
+		this.renderLabel();
+	}, { attribute: "name" });
+	/** The line under the name: their role, their company. */
+	description = this.useChange("", (value) => {
+		this._refs.description.textContent = value;
+		this._refs.description.hidden = value === "";
+		this.renderLabel();
+	}, { attribute: "description" });
+	/** Their picture; their initials without it. */
+	src = this.useChange("", (value) => this._refs.avatar.src.set(value), { attribute: "src" });
+	/** Their account's address: the button becomes a link. */
+	href = this.useChange("", () => this.renderLink(), { attribute: "href" });
+	/** The avatar alone. */
+	compact = this.useChange(false, (value) => this.reflect("compact", value), { attribute: "compact" });
+	_refs = this.useRefs((ref) => ({
+		avatar: ref("jl-avatar"),
+		button: ref("button"),
+		content: ref(".content"),
+		description: ref(".description"),
+		link: ref("a"),
+		name: ref(".name")
+	}));
+	focus(options) {
+		this.control().focus(options);
+	}
+	templateHtml() {
+		const avatar = /* @__PURE__ */ jsx(JlAvatar, { size: "md" });
+		avatar.setAttribute("aria-hidden", "true");
+		return /* @__PURE__ */ jsxs(Fragment, { children: [/* @__PURE__ */ jsx("button", {
+			type: "button",
+			class: "base",
+			attrs: { part: "base" },
+			children: /* @__PURE__ */ jsxs("span", {
+				class: "content",
+				children: [avatar, /* @__PURE__ */ jsxs("span", {
+					class: "text",
+					children: [/* @__PURE__ */ jsx("span", { class: "name" }), /* @__PURE__ */ jsx("span", {
+						class: "description",
+						hidden: true
+					})]
+				})]
+			})
+		}), /* @__PURE__ */ jsx("a", {
+			class: "base",
+			hidden: true,
+			attrs: { part: "base" }
+		})] });
+	}
+	templateCss() {
+		return css`${BASE_STYLES}${jl_account_button_default}`;
+	}
+	onConnect() {
+		this.on(this._refs.button, "click", () => this.events.emit("press"));
+		this.on(this._refs.link, "click", () => this.events.emit("press"));
+	}
+	control() {
+		return this.href.get() === "" ? this._refs.button : this._refs.link;
+	}
+	/** Moves the content into the link or back into the button. */
+	renderLink() {
+		const { button, content, link } = this._refs;
+		const href = this.href.get();
+		this.control().append(content);
+		button.hidden = href !== "";
+		link.hidden = href === "";
+		setOrRemove(link, "href", href);
+	}
+	/** Its name for screen readers and its tooltip: the name, then the line under it. */
+	renderLabel() {
+		const label = [this.name.get(), this.description.get()].filter((part) => part !== "").join(", ");
+		for (const control of [this._refs.button, this._refs.link]) {
+			setOrRemove(control, "title", this.name.get());
+			setOrRemove(control, "aria-label", label);
+		}
+	}
+};
+JlAccountButton.register();
+export { JlAccountButton };

package/dist/molecules/jl-alert.d.ts

@@ -1,8 +1,9 @@
 import { JlElement } from '../base/jl-element';
 import type { Tone } from '../types/options.types';
 /**
- * A message in the flow of the page, coloured by its tone: a tip, a success, a warning, an error. The text goes
- * in the default slot, buttons in `slot="actions"`. A `dismissible` alert has an × that hides it.
+ * A message in the flow of the page, coloured by its tone: a tip, a success, a warning, an error. The text is the
+ * `description` or goes in the default slot (for links and markup), buttons in `slot="actions"`. A `dismissible`
+ * alert has an × that hides it.
  */
 export declare class JlAlert extends JlElement {
     static readonly selector = "jl-alert";
@@ -17,6 +18,11 @@ export declare class JlAlert extends JlElement {
         get(): string;
         set(setter: string | ((prevState: string) => string)): void;
     }>>;
+    /** The message as plain text, for pages that set it from code; richer content goes in the default slot. */
+    readonly description: Readonly<Readonly<{
+        get(): string;
+        set(setter: string | ((prevState: string) => string)): void;
+    }>>;
     /** An icon name in place of the tone's own; `none` shows no icon. */
     readonly icon: Readonly<Readonly<{
         get(): string;
@@ -33,7 +39,8 @@ export declare class JlAlert extends JlElement {
     templateHtml(): Node;
     templateCss(): string;
     onConnect(): void;
-    private renderActions;
+    /** Empty parts take no room: an alert with only a description has no blank line under it. */
+    private renderSlots;
     /** The tone's own icon is filled, as a toast's is; an icon of the page's stays as it is drawn. */
     private renderIcon;
 }

package/dist/molecules/jl-alert.js

@@ -31,8 +31,9 @@ var TONE_ROLES = {
 	warn: "alert"
 };
 /**
-* A message in the flow of the page, coloured by its tone: a tip, a success, a warning, an error. The text goes
-* in the default slot, buttons in `slot="actions"`. A `dismissible` alert has an × that hides it.
+* A message in the flow of the page, coloured by its tone: a tip, a success, a warning, an error. The text is the
+* `description` or goes in the default slot (for links and markup), buttons in `slot="actions"`. A `dismissible`
+* alert has an × that hides it.
 */
 var JlAlert = class extends JlElement {
 	static selector = "jl-alert";
@@ -49,6 +50,11 @@ var JlAlert = class extends JlElement {
 		this._refs.heading.textContent = value;
 		this._refs.heading.hidden = value === "";
 	}, { attribute: "heading" });
+	/** The message as plain text, for pages that set it from code; richer content goes in the default slot. */
+	description = this.useChange("", (value) => {
+		this._refs.description.textContent = value;
+		this._refs.description.hidden = value === "";
+	}, { attribute: "description" });
 	/** An icon name in place of the tone's own; `none` shows no icon. */
 	icon = this.useChange("", () => this.renderIcon(), { attribute: "icon" });
 	/** Shows an × that hides the alert and fires `dismiss`. */
@@ -61,8 +67,11 @@ var JlAlert = class extends JlElement {
 		actionsSlot: ref("slot[name=\"actions\"]"),
 		alert: ref(".alert"),
 		close: ref(".close"),
+		description: ref(".description"),
 		heading: ref(".heading"),
-		icon: ref(".icon")
+		icon: ref(".icon"),
+		text: ref(".text"),
+		textSlot: ref("slot:not([name])")
 	}));
 	/** Hides the alert as its × does, and fires `dismiss`. */
 	dismiss() {
@@ -86,8 +95,13 @@ var JlAlert = class extends JlElement {
 							class: "heading",
 							hidden: true
 						}),
+						/* @__PURE__ */ jsx("p", {
+							class: "description",
+							hidden: true
+						}),
 						/* @__PURE__ */ jsx("div", {
 							class: "text",
+							hidden: true,
 							children: /* @__PURE__ */ jsx("slot", {})
 						}),
 						/* @__PURE__ */ jsx("div", {
@@ -113,10 +127,13 @@ var JlAlert = class extends JlElement {
 	}
 	onConnect() {
 		this._refs.close.events.register("press", () => this.dismiss());
-		this.renderActions();
-		this.on(this._refs.actionsSlot, "slotchange", () => this.renderActions());
+		this.renderSlots();
+		this.on(this._refs.actionsSlot, "slotchange", () => this.renderSlots());
+		this.on(this._refs.textSlot, "slotchange", () => this.renderSlots());
 	}
-	renderActions() {
+	/** Empty parts take no room: an alert with only a description has no blank line under it. */
+	renderSlots() {
+		this._refs.text.hidden = !hasSlotted(this._refs.textSlot);
 		this._refs.actions.hidden = !hasSlotted(this._refs.actionsSlot);
 	}
 	/** The tone's own icon is filled, as a toast's is; an icon of the page's stays as it is drawn. */

package/dist/molecules/jl-chip-group.css_raw.js

@@ -0,0 +1,3 @@
+// src/molecules/jl-chip-group.css?raw
+var jl_chip_group_default = ":host {\n  display: block;\n  min-width: 0;\n  --height: 28px;\n  --pad: 10px;\n  --font-size: var(--jl-font-sm);\n}\n\n:host([size=\"sm\"]) {\n  --height: 24px;\n  --pad: 8px;\n  --font-size: var(--jl-font-xs);\n}\n\n/* Where a thumb presses it. */\n:host([size=\"lg\"]) {\n  --height: 36px;\n  --pad: 14px;\n  --font-size: var(--jl-font-md);\n}\n\n/*\n * One row that scrolls sideways on a narrow screen. The padding keeps the focus ring inside what the scroller\n * clips; the negative margin keeps the chips aligned with the content around.\n */\n.group {\n  display: flex;\n  gap: 8px;\n  min-width: 0;\n  margin: -3px;\n  padding: 3px;\n  overflow-x: auto;\n  scrollbar-width: none;\n  contain: inline-size;\n}\n\n.group::-webkit-scrollbar {\n  display: none;\n}\n\n:host([wrap]) .group {\n  flex-wrap: wrap;\n  overflow: visible;\n  contain: none;\n}\n\n.chip {\n  display: inline-flex;\n  flex: none;\n  align-items: center;\n  gap: 6px;\n  max-width: 100%;\n  height: var(--height);\n  padding: 0 var(--pad);\n  border: 1px solid var(--jl-line-strong);\n  border-radius: var(--jl-radius-pill);\n  background: var(--jl-surface);\n  color: var(--jl-text-2);\n  font-size: var(--font-size);\n  font-weight: 600;\n  line-height: 1;\n  white-space: nowrap;\n  cursor: pointer;\n  transition:\n    background var(--jl-fast) var(--jl-ease),\n    border-color var(--jl-fast) var(--jl-ease),\n    color var(--jl-fast) var(--jl-ease);\n}\n\n.chip:hover:not(:disabled) {\n  background: var(--jl-surface-2);\n}\n\n.chip.selected,\n.chip.selected:hover:not(:disabled) {\n  border-color: var(--jl-accent-line);\n  background: var(--jl-accent-soft);\n  color: var(--jl-accent);\n}\n\n.chip:disabled {\n  cursor: not-allowed;\n  opacity: 0.5;\n}\n\n/* A line box taller than the chip's own line-height of 1: the accents of É, Â, Ö stay inside what overflow clips. */\n.label {\n  overflow: hidden;\n  line-height: 1.4;\n  text-overflow: ellipsis;\n}\n\n.badge {\n  min-width: 18px;\n  margin-right: -4px;\n  padding: 0 6px;\n  border-radius: var(--jl-radius-pill);\n  background: var(--jl-surface-3);\n  color: var(--jl-muted);\n  font-size: var(--jl-font-xs);\n  font-variant-numeric: tabular-nums;\n  font-weight: 650;\n  line-height: 18px;\n  text-align: center;\n}\n\n.chip.selected .badge {\n  background: color-mix(in srgb, var(--jl-accent) 14%, transparent);\n  color: var(--jl-accent);\n}\n";
+export { jl_chip_group_default as default };

package/dist/molecules/jl-chip-group.d.ts

@@ -0,0 +1,81 @@
+import { JlFormControl } from '../base/jl-form-control';
+import type { ChipGroupOption } from '../types/jl-chip-group.types';
+import type { ControlSize } from '../types/options.types';
+/**
+ * A row of chips to choose from: a status to filter by, a category, a reason. One choice by default, as radios
+ * (choosing the chosen chip again keeps it); `multiple` lets people turn each chip on and off. On a narrow screen
+ * the row scrolls sideways; `wrap` lets it go to the next line instead. `change` fires with the chosen values.
+ */
+export declare class JlChipGroup extends JlFormControl {
+    static readonly selector = "jl-chip-group";
+    readonly events: Readonly<import("@jadis/core").UseEventsHandler<{
+        change: string[];
+    }>>;
+    readonly options: Readonly<Readonly<{
+        get(): ChipGroupOption[];
+        set(setter: ChipGroupOption[] | ((prevState: ChipGroupOption[]) => ChipGroupOption[])): void;
+    }>>;
+    /** The chosen values, in the options' order; with one choice, a list of at most one. */
+    readonly value: Readonly<Readonly<{
+        get(): string[];
+        set(setter: string[] | ((prevState: string[]) => string[])): void;
+    }>>;
+    /** Several chips can be chosen, each turned on and off on its own. */
+    readonly multiple: Readonly<Readonly<{
+        get(): boolean;
+        set(setter: boolean | ((prevState: boolean) => boolean)): void;
+    }>>;
+    /** Goes to the next line when the chips do not fit, instead of scrolling sideways. */
+    readonly wrap: Readonly<Readonly<{
+        get(): boolean;
+        set(setter: boolean | ((prevState: boolean) => boolean)): void;
+    }>>;
+    readonly size: Readonly<Readonly<{
+        get(): ControlSize;
+        set(setter: ((prevState: ControlSize) => ControlSize) | ControlSize): void;
+    }>>;
+    /** The group's name for screen readers, when no visible label names it. */
+    readonly label: Readonly<Readonly<{
+        get(): string;
+        set(setter: string | ((prevState: string) => string)): void;
+    }>>;
+    /** A form refuses to submit while nothing is chosen. */
+    readonly required: Readonly<Readonly<{
+        get(): boolean;
+        set(setter: boolean | ((prevState: boolean) => boolean)): void;
+    }>>;
+    readonly disabled: Readonly<Readonly<{
+        get(): boolean;
+        set(setter: boolean | ((prevState: boolean) => boolean)): void;
+    }>>;
+    /** The chip that holds the Tab stop with several choices: the last one people reached. */
+    private readonly _state;
+    private readonly _nameWatch;
+    private readonly _refs;
+    /** Focuses the chip that holds the Tab stop. */
+    focus(options?: FocusOptions): void;
+    templateHtml(): Node;
+    templateCss(): string;
+    onConnect(): void;
+    onDisconnect(): void;
+    protected resetValue(): void;
+    /** The browser calls it for a disabled fieldset and for the element's own `disabled`, even before it renders. */
+    protected setDisabledByForm(disabled: boolean): void;
+    private chips;
+    /** What is chosen: with one choice, only the first value counts. */
+    private chosen;
+    private isDisabled;
+    /** One choice: the chip becomes it. Several: the chip turns on or off, the values keeping the options' order. */
+    private press;
+    private commit;
+    private onKeydown;
+    private renderOptions;
+    private chip;
+    /** Radios with one choice, toggle buttons with several; each chosen chip shows its icon or a check. */
+    private renderValue;
+    /** Tab reaches one chip: the chosen one with one choice, the last one reached with several, else the first. */
+    private renderTabStop;
+    /** One choice gives one entry; several give one entry each under the field's name, as checkboxes would. */
+    private renderFormValue;
+    private renderValidity;
+}