jsl-ui 9.29.0 → 10.0.0

package/examples/showcase/cultures.ts

@@ -0,0 +1,39 @@
+import culture from "../../core/culture";
+import { date } from "../../core/date";
+import { numeric } from "../../core/numeric";
+
+export const showcaseCultures = [
+    { id: "", label: "Default (ISO)" },
+    { id: "de", label: "Deutsch (de)" },
+    { id: "en-us", label: "English (en-us)" },
+    { id: "en-gb", label: "English (en-gb)" }
+] as const;
+
+const storageKey = "jsl-showcase-culture";
+const picker = document.getElementById("showcase-culture") as HTMLSelectElement;
+const preview = document.getElementById("showcase-format-preview");
+const normalize = (id: string) => showcaseCultures.find(item => item.id === id?.toLowerCase())?.id ?? "";
+let saved = "";
+try { saved = localStorage.getItem(storageKey) ?? ""; } catch { /* URL selection works without storage. */ }
+const selected = normalize(new URL(location.href).searchParams.get("culture") ?? saved);
+
+// This module runs before sample modules construct controls with formatted values.
+culture.set(selected);
+picker.replaceChildren(...showcaseCultures.map(item => {
+    const option = document.createElement("option");
+    option.value = item.id; option.textContent = item.label;
+    return option;
+}));
+picker.value = selected;
+preview.textContent = date.format(new Date(2026, 9, 23)) + " · " + numeric.format(1234.56, "#,0.00");
+
+/** Reinitialize the examples so existing input strings aren't parsed under a new culture. */
+export function changeCulture(id: string): void {
+    const next = normalize(id);
+    if (next === selected) { return; }
+    try { localStorage.setItem(storageKey, next); } catch { /* Keep selection in the URL instead. */ }
+    const url = new URL(location.href);
+    url.searchParams.set("culture", next);
+    location.assign(url.href);
+}
+picker.addEventListener("change", () => changeCulture(picker.value));

package/examples/showcase/dates.ts

@@ -0,0 +1,182 @@
+import { IJSLComponent, IJSLVNode } from "jsl-render";
+import { noUiSlider } from "../../components/slider/nouislider";
+import { DateComponent } from "../../components/date/DateComponent";
+import { DateRangeComponent } from "../../components/date-range/DateRangeComponent";
+import { DateTimeComponent } from "../../components/date-time/DateTimeComponent";
+import { ButtonComponent } from "../../components/button/ButtonComponent";
+import { DialogComponent } from "../../components/dialog/DialogComponent";
+import { DatePicker, IDatePicker } from "../../ui/date.picker";
+import { date } from "../../core/date";
+
+type Content = IJSLVNode | IJSLComponent;
+const text = (tag: string, content: string, className?: string): IJSLVNode => ({ tag, content, attr: { class: className } });
+const group = (children: Content[], className?: string): IJSLVNode => ({ tag: "div", attr: { class: className }, children });
+const status = (content: string) => ({ tag: "p", content, attr: { class: "sample-status", role: "status" } });
+const format = (value: Date) => value ? date.format(value) : "No date selected";
+const day = (n: number, hours = 9, minutes = 30, seconds = 0) => new Date(2026, 9, n, hours, minutes, seconds);
+const code = (content: string) => text("pre", content, "sample-code");
+const action = (content: string, click: () => void) => new ButtonComponent({ content, click, type: "button", outlined: true, size: "small" });
+const field = (id: string, label: string, control: Content) => group([
+    { tag: "label", content: label, attr: { for: id } }, control
+], "date-showcase-field");
+
+class SliderSample implements IJSLComponent {
+    private slider: any;
+    constructor(private options: { start: number[]; disabled?: boolean; vertical?: boolean; tooltips?: boolean; }) {}
+    render(): IJSLVNode {
+        return { tag: "div", attr: {
+            class: "showcase-slider" + (this.options.vertical ? " showcase-slider-vertical" : ""),
+            disabled: this.options.disabled ? "" : undefined
+        } };
+    }
+    onCreate(node: IJSLVNode) {
+        const count = this.options.start.length;
+        this.slider = noUiSlider.create(node.dom, {
+            start: this.options.start, range: { min: 0, max: 100 }, step: 1,
+            connect: count === 2 ? true : [true, false],
+            orientation: this.options.vertical ? "vertical" : "horizontal",
+            direction: this.options.vertical ? "rtl" : "ltr",
+            tooltips: this.options.tooltips ? { to: value => Math.round(value) + "%" } : false
+        });
+        node.dom.querySelectorAll<HTMLElement>("[role=slider]").forEach((handle, index) => {
+            handle.setAttribute("aria-label", count === 2 ? (index === 0 ? "Lower value" : "Upper value") : "Value");
+            if (this.options.disabled) {
+                handle.setAttribute("tabindex", "-1");
+                handle.setAttribute("aria-disabled", "true");
+            }
+        });
+        // Sibling nodes are available after the renderer finishes mounting.
+        Promise.resolve().then(() => this.slider?.on("update", values => {
+            const readout = node.dom.parentElement?.querySelector<HTMLElement>(".slider-readout");
+            if (readout) { readout.textContent = values.map(value => Math.round(+value) + "%").join(" – "); }
+        }));
+    }
+    onRemove() { this.slider?.destroy(); this.slider = null; }
+}
+
+class CalendarSample implements IJSLComponent {
+    private picker: IDatePicker;
+    render(): IJSLVNode { return group([], "showcase-calendar"); }
+    onCreate(node: IJSLVNode) {
+        this.picker = DatePicker(node.dom, { mode: "dp-permanent", hilightedDate: day(15) });
+    }
+    onRemove() { this.picker?.destroy(); }
+}
+
+function card(id: string, number: string, title: string, description: string, children: Content[]): IJSLVNode {
+    return { tag: "article", attr: { class: "sample-card", id }, children: [
+        group([text("span", number, "sample-number"), text("h3", title)], "card-heading"),
+        text("p", description, "card-description"), ...children
+    ] };
+}
+function section(id: string, number: string, title: string, description: string, preview: Content, cards: IJSLVNode[], usage: Content[]): IJSLVNode {
+    return { tag: "section", attr: { id, class: "component-section", "aria-labelledby": id + "-title" }, children: [
+        group([
+            group([text("p", "THE ESSENTIALS / " + number, "eyebrow"),
+                { tag: "h2", content: title, attr: { id: id + "-title", class: "section-title" } },
+                text("p", description, "hero-description")], "hero-copy"),
+            group([text("span", "INTERACTIVE PREVIEW", "preview-caption"), preview], "hero-preview date-hero-preview")
+        ], "hero"),
+        group(cards, "sample-grid date-sample-grid"),
+        { tag: "details", attr: { class: "usage" }, children: [text("summary", title + " usage & compatibility"), ...usage] }
+    ] };
+}
+const sliderPreview = group([new SliderSample({ start: [30, 75] }), text("span", "", "slider-readout")], "slider-sample");
+export const sliderShowcase = section("sliders", "04", "Sliders",
+    "A lighter track, a precise handle. Move a value or narrow a range.", sliderPreview, [
+        card("slider-single", "01", "A single value", "Click the track, drag the handle, or use the arrow keys. Home and End reach the limits.", [
+            group([new SliderSample({ start: [45], tooltips: true }), text("span", "", "slider-readout")], "slider-sample slider-with-tooltip")
+        ]),
+        card("slider-states", "02", "Different directions", "The same design supports vertical sliders and disabled controls.", [
+            group([new SliderSample({ start: [65], vertical: true }),
+                group([text("p", "Unavailable range", "inline-note"), new SliderSample({ start: [20, 80], disabled: true })], "slider-disabled-example")
+            ], "slider-orientations")
+        ])
+    ], [
+        code('noUiSlider.create(element, {\n  start: [25, 75], connect: true, step: 1,\n  range: { min: 0, max: 100 }\n});'),
+        text("p", "The bundled noUiSlider API is preserved. Its CSS now uses the shared theme, including handles, tooltips, pips, and disabled states. Use aria-label on handles to describe their meaning. Override --jsl-slider-track and --jsl-slider-connect for a particular slider.")
+    ]);
+
+const dateStatus = status("Choose a day or enter a date.");
+const customStatus = status("Uses day/month/year formatting.");
+export const dateShowcase = section("dates", "05", "Dates",
+    "Type a date or pick a day. A calmer calendar for everyday planning.", new CalendarSample(), [
+        card("date-basic", "01", "A date, simply", "Focus the field to open the calendar. Arrow Down moves into it; Escape returns to the field.", [
+            field("showcase-date-basic", "Due date", new DateComponent({ id: "showcase-date-basic", value: day(15), onChange: value => { dateStatus.content = format(value); } })),
+            dateStatus,
+            field("showcase-date-disabled", "Unavailable date", new DateComponent({ id: "showcase-date-disabled", value: day(20), enabled: false }))
+        ]),
+        card("date-custom", "02", "Your format, your availability", "A custom formatter and parser, with October weekdays available for selection.", [
+            field("showcase-date-custom", "Appointment date (DD/MM/YYYY)", new DateComponent({
+                id: "showcase-date-custom", value: day(19), min: day(1), max: day(31),
+                format: value => date.format(value, "dd/mm/yy"),
+                parse: value => date.parse(value, "dd/mm/yy"),
+                inRange: value => value.getDay() !== 0 && value.getDay() !== 6,
+                onChange: value => { customStatus.content = value ? date.format(value, "dd/mm/yy") : "No date selected"; }
+            })), customStatus,
+            text("p", "Invalid or unavailable dates stay in the field for correction and do not raise onChange.", "inline-note")
+        ])
+    ], [
+        code('new DateComponent({\n  value: new Date(2026, 9, 15),\n  min: new Date(2026, 9, 1), max: new Date(2026, 9, 31),\n  onChange: value => console.log(value)\n});'),
+        text("p", "Existing formatting, parsing, localization, dateClass, inRange, binding, and getRef options remain available. Empty fields return null. setValue(date) updates the field and calendar silently. getRef().setState(state) retains its selection events; pass true as a second argument for a silent update."),
+        text("p", "Calendar controls support Tab, Enter, Space, arrow keys, and Escape. Use ariaLabel or an associated label for the field. Popups within dialogs stay inside the dialog; appendTo allows an explicit popup container.")
+    ]);
+
+const rangeStatus = status("October 8 – October 22, 2026");
+const mainRange = new DateRangeComponent({
+    min: day(1), max: day(31), minValue: day(8), maxValue: day(22), increment: "days",
+    onChange: value => { rangeStatus.content = format(value.minValue) + " – " + format(value.maxValue); }
+});
+export const dateRangeShowcase = section("date-ranges", "06", "Date ranges",
+    "Two dates, one selection. Fine-tune either endpoint or move the handles.", new DateRangeComponent({
+        min: day(1), max: day(31), minValue: day(10), maxValue: day(24), increment: "days"
+    }), [
+        card("range-basic", "01", "Choose a window", "The fields and slider stay in sync. Endpoints stay ordered and within the available dates.", [mainRange, rangeStatus]),
+        card("range-disabled", "02", "Fixed and unavailable", "Disabled inputs and handles preserve a range. A single available day is supported too.", [
+            new DateRangeComponent({ min: day(1), max: day(31), minValue: day(8), maxValue: day(22), increment: "days", enabled: false }),
+            text("p", "One available day", "inline-note"),
+            new DateRangeComponent({ min: day(15), max: day(15), increment: "days", ariaLabel: "Single available day" })
+        ])
+    ], [
+        code('new DateRangeComponent({\n  min, max, minValue: start, maxValue: end,\n  increment: "days",\n  onChange: ({ minValue, maxValue }) => { /* Selected dates */ }\n});'),
+        text("p", "getMin(), getMax(), and the existing range options are preserved. Daily increments remain the supported mode. onChange reports both endpoints once for each changed range, and is silent during initialization. enabled, ariaLabel, startLabel, and endLabel are optional additions.")
+    ]);
+
+const timeStatus = status("Pick a date and enter a time.");
+const dateTimeModel = { appointment: day(21, 14, 45) };
+const boundStatus = status("October 21 at 14:45");
+const boundDateTime = new DateTimeComponent({
+    id: "showcase-datetime-bound", bindTo: dateTimeModel, property: "appointment", bindMode: "both",
+    onChange: value => { boundStatus.content = value ? format(value) + " at " + date.formatTime(value, "HourMinute") : "Appointment cleared"; }
+});
+export const dateTimeShowcase = section("date-times", "07", "Date & time",
+    "A day and a moment, together. Familiar fields with room for precision.", new DateTimeComponent({
+        id: "showcase-datetime-preview", value: day(15, 10, 30), ariaLabel: "Preview appointment"
+    }), [
+        card("datetime-basic", "01", "Plan a precise moment", "Use hours and minutes, or include seconds when the details matter.", [
+            field("showcase-datetime-seconds", "Scheduled start", new DateTimeComponent({
+                id: "showcase-datetime-seconds", inputMode: "HourMinuteSecond", value: day(15, 9, 30, 15),
+                onChange: value => { timeStatus.content = value ? format(value) + " at " + date.formatTime(value, "HourMinuteSecond") : "No complete date and time"; }
+            })), timeStatus,
+            field("showcase-datetime-disabled", "Unavailable schedule", new DateTimeComponent({ id: "showcase-datetime-disabled", value: day(15), enabled: false }))
+        ]),
+        card("datetime-model", "02", "Connected to your application", "Changes update the model. A model change refreshes both fields.", [
+            field("showcase-datetime-bound", "Appointment", boundDateTime),
+            group([action("Move to October 26", () => {
+                dateTimeModel.appointment = day(26, 11, 15);
+                boundStatus.content = "Model updated to October 26 at 11:15.";
+            }), action("Open in a dialog", () => {
+                DialogComponent.show({
+                    header: "Schedule an appointment", width: "28rem",
+                    content: group([
+                        text("p", "Choose a date and time. Escape closes the calendar first.", "card-description"),
+                        field("showcase-dialog-date", "Appointment", new DateTimeComponent({ id: "showcase-dialog-date", value: day(21, 14, 45) }))
+                    ]), footer: group([DialogComponent.Cancel(), DialogComponent.Ok()], "sample-row")
+                });
+            })], "sample-row"), boundStatus
+        ])
+    ], [
+        code('new DateTimeComponent({\n  value: new Date(2026, 9, 15, 9, 30),\n  inputMode: "HourMinute", // Or "HourMinuteSecond"\n  bindTo: model, property: "appointment", bindMode: "both",\n  onChange: value => console.log(value)\n});'),
+        text("p", "The existing Date-valued callbacks, converters, getValue(), and getValueAsDate() remain available. toModel, fromModel, and both binding modes are supported. An incomplete value returns null; malformed dates and times do not update the model. setValue(date) silently updates both fields."),
+        text("p", "The supplied id belongs to the date field; the time field gets an id with '-time' appended. ariaLabel names the group, and dateAriaLabel and timeAriaLabel can name its fields. Date-only formatting and parsing options apply to the date field.")
+    ]);

package/examples/showcase/dialogs.ts

@@ -0,0 +1,184 @@
+import { IJSLVNode } from "jsl-render";
+import { DialogComponent } from "../../components/dialog/DialogComponent";
+import { ButtonComponent } from "../../components/button/ButtonComponent";
+
+const text = (tag: string, content: string, className?: string): IJSLVNode => ({ tag, content, attr: { class: className } });
+const actions = (...children: IJSLVNode[]): IJSLVNode => ({ tag: "div", children });
+const message = (content: string): IJSLVNode => ({ tag: "p", content, attr: { class: "sample-status", role: "status" } });
+const launch = (content: string, id: string, click: () => void) => new ButtonComponent({ content, class: id, type: "button", outlined: true, click });
+
+const confirmationStatus = message("Choose an action inside the dialog.");
+function showConfirmation() {
+    DialogComponent.show({
+        header: "Save your changes?",
+        content: { tag: "div", attr: { class: "showcase-dialog-copy" }, children: [
+            text("p", "Your workspace has been updated. Save your changes to keep everything in sync."),
+            { tag: "div", attr: { class: "dialog-summary" }, children: [
+                text("span", "Workspace", "dialog-summary-label"), text("strong", "Product design"),
+                text("span", "Changes", "dialog-summary-label"), text("span", "Settings and permissions")
+            ] }
+        ] },
+        footer: actions(DialogComponent.Cancel(), DialogComponent.Button({
+            content: "Save changes", class: "dlg-ok-btn",
+            onClick: () => { confirmationStatus.content = "Changes saved."; }
+        })),
+        width: "29rem", showCloseButton: true
+    });
+}
+
+const formStatus = message("Create a project without leaving the page.");
+function showForm() {
+    const nameId = "showcase-project-name";
+    const formId = "showcase-project-form";
+    DialogComponent.show({
+        header: "Create a project",
+        content: { tag: "form", attr: { id: formId, class: "showcase-dialog-copy", submit: (event: Event) => event.preventDefault() }, children: [
+            text("p", "Give your team a place to organize its next idea."),
+            { tag: "div", attr: { class: "dialog-form-field" }, children: [
+                { tag: "label", content: "Project name", attr: { for: nameId } },
+                { tag: "input", attr: { id: nameId, name: "name", type: "text", required: "required", placeholder: "e.g. Website refresh", maxlength: 80 } }
+            ] },
+            { tag: "div", attr: { class: "dialog-form-field" }, children: [
+                { tag: "label", content: "Description (optional)", attr: { for: "showcase-project-notes" } },
+                { tag: "textarea", attr: { id: "showcase-project-notes", name: "notes", rows: 3, placeholder: "What are you working on?" } }
+            ] }
+        ] },
+        footer: actions(DialogComponent.Cancel(), DialogComponent.Button({
+            content: "Create project", class: "dlg-ok-btn", onClick: () => {
+                const form = document.getElementById(formId) as HTMLFormElement;
+                const name = document.getElementById(nameId) as HTMLInputElement;
+                if (!form.reportValidity() || !name.value.trim()) {
+                    return false;
+                }
+                formStatus.content = 'Project "' + name.value.trim() + '" created.';
+            }
+        })),
+        showCloseButton: true, autoFocus: "#" + nameId, OkOnEnter: true
+    });
+}
+
+function showLongContent() {
+    DialogComponent.show({
+        header: "Workspace access",
+        content: { tag: "div", attr: { class: "showcase-dialog-copy" }, children: [
+            text("p", "Review who can access this workspace. The actions stay in view while this list scrolls."),
+            ...Array.from({ length: 18 }, (_, index): IJSLVNode => ({
+                tag: "div", attr: { class: "dialog-member" }, children: [
+                    text("span", ("0" + (index + 1)).slice(-2), "dialog-member-avatar"),
+                    { tag: "div", children: [text("strong", "Team member " + (index + 1)), text("span", "member" + (index + 1) + "@example.com")] },
+                    text("span", index === 0 ? "Owner" : "Member", "dialog-member-role")
+                ]
+            }))
+        ] },
+        footer: actions(DialogComponent.Button({ content: "Done", class: "dlg-ok-btn" })),
+        width: "36rem", height: "22rem", showCloseButton: true
+    });
+}
+
+function showWorkspace(modal = true) {
+    DialogComponent.show({
+        header: "Workspace details",
+        content: { tag: "div", attr: { class: "showcase-dialog-copy" }, children: [
+            text("p", "Drag the title bar to move this dialog. Use the handle in the bottom-right corner to resize it."),
+            { tag: "div", attr: { class: "dialog-summary" }, children: [
+                text("span", "Workspace", "dialog-summary-label"), text("strong", "Product design"),
+                text("span", "Visibility", "dialog-summary-label"), text("span", "Private"),
+                text("span", "Members", "dialog-summary-label"), text("span", "18 people")
+            ] },
+            text("p", modal ? "The background stays still while you work." : "This is a non-modal dialog. You can still use the showcase and change its theme.", "dialog-help")
+        ] },
+        footer: actions(DialogComponent.Button({ content: "Done" })),
+        width: "36rem", height: "15rem", showCloseButton: true,
+        allowMove: true, allowResize: true, modal,
+        resizeOptions: { minWidth: 280, minHeight: 240, maxWidth: 960, maxHeight: 760 }
+    });
+}
+
+const nestedStatus = message("Open a second dialog from the first.");
+function showNested() {
+    DialogComponent.show({
+        header: "Manage workspace",
+        content: { tag: "div", attr: { class: "showcase-dialog-copy" }, children: [
+            text("p", "Review a permission before making changes. Closing the second dialog returns you here."),
+            new ButtonComponent({ content: "Review permissions", outlined: true, type: "button", class: "dialog-open-nested", click: () => {
+                DialogComponent.show({
+                    header: "Confirm access",
+                    content: "Allow team members to invite others to this workspace?",
+                    footer: actions(DialogComponent.Cancel(), DialogComponent.Ok(() => { nestedStatus.content = "Permission confirmed."; })),
+                    width: "27rem", showCloseButton: true
+                });
+            } })
+        ] },
+        footer: actions(DialogComponent.Cancel(), DialogComponent.Button({ content: "Done" })),
+        width: "30rem", showCloseButton: true
+    });
+}
+
+const asyncStatus = message("Try saving, or simulate a failed save.");
+function showAsync() {
+    const notice = message("Your changes are ready to save.");
+    DialogComponent.show({
+        header: "Save workspace",
+        content: { tag: "div", attr: { class: "showcase-dialog-copy" }, children: [
+            text("p", "The save action waits for the result before closing. A failed save keeps the dialog open so you can try again."),
+            { tag: "label", attr: { class: "dialog-check" }, children: [
+                { tag: "input", attr: { id: "showcase-failed-save", type: "checkbox" } }, text("span", "Simulate a failed save")
+            ] }, notice
+        ] },
+        footer: actions(DialogComponent.Cancel(), DialogComponent.Button({
+            content: "Save changes", class: "dlg-ok-btn", onClick: async () => {
+                const fail = (document.getElementById("showcase-failed-save") as HTMLInputElement).checked;
+                notice.content = "Saving changes...";
+                await new Promise(resolve => setTimeout(resolve, 750));
+                if (fail) {
+                    notice.content = "Could not save. Uncheck the option and try again.";
+                    return false;
+                }
+                asyncStatus.content = "Workspace saved successfully.";
+            }
+        })),
+        showCloseButton: true, closeOnOverlayClick: false
+    });
+}
+
+function card(id: string, number: string, title: string, description: string, children: Array<IJSLVNode | ButtonComponent>): IJSLVNode {
+    return { tag: "article", attr: { class: "sample-card", id, "aria-labelledby": id + "-title" }, children: [
+        { tag: "div", attr: { class: "card-heading" }, children: [text("span", number, "sample-number"), { tag: "h3", content: title, attr: { id: id + "-title" } }] },
+        text("p", description, "card-description"), ...children
+    ] };
+}
+
+export const dialogShowcase: IJSLVNode = {
+    tag: "section", attr: { id: "dialogs", class: "component-section", "aria-labelledby": "dialogs-title" }, children: [
+        { tag: "div", attr: { class: "hero" }, children: [
+            { tag: "div", attr: { class: "hero-copy" }, children: [
+                text("p", "THE ESSENTIALS / 02", "eyebrow"),
+                { tag: "h2", content: "Dialogs", attr: { id: "dialogs-title", class: "section-title" } },
+                text("p", "A little focus for the task at hand. Clear content, accessible controls, and room to work.", "hero-description")
+            ] },
+            { tag: "div", attr: { class: "hero-preview" }, children: [
+                text("span", "INTERACTIVE PREVIEW", "preview-caption"),
+                new ButtonComponent({ content: "Open a dialog", size: "large", type: "button", class: "dialog-launch-hero", click: showConfirmation }),
+                text("span", "Try it in any theme.", "preview-note")
+            ] }
+        ] },
+        { tag: "div", attr: { class: "overview-bar" }, children: [text("span", "Overview", "overview-label"), text("span", "Responsive layout", "overview-stat"), text("span", "Keyboard accessible", "overview-stat")] },
+        { tag: "div", attr: { class: "sample-grid dialog-sample-grid" }, children: [
+            card("dialogs-basic", "01", "Focused decisions", "A title, a short explanation, and a clear next step.", [launch("Open confirmation", "dialog-launch-basic", showConfirmation), confirmationStatus]),
+            card("dialogs-form", "02", "Collect a little more", "Autofocus, native validation, and Enter to confirm. Textareas keep their line breaks.", [launch("Open project form", "dialog-launch-form", showForm), formStatus]),
+            card("dialogs-scroll", "03", "Room for more", "Long content scrolls within the dialog while the title and actions stay visible.", [launch("Open long content", "dialog-launch-scroll", showLongContent)]),
+            card("dialogs-resize", "04", "Make room", "Move and resize a dialog, or keep the page interactive with a non-modal version.", [
+                { tag: "div", attr: { class: "sample-row" }, children: [launch("Move & resize", "dialog-launch-resize", () => showWorkspace()), launch("Non-modal", "dialog-launch-nonmodal", () => showWorkspace(false))] }
+            ]),
+            card("dialogs-nested", "05", "One decision at a time", "Nested dialogs keep keyboard focus and Escape scoped to the active dialog.", [launch("Open nested dialogs", "dialog-launch-nested", showNested), nestedStatus]),
+            card("dialogs-async", "06", "Wait for the result", "Async actions prevent duplicate submissions. Return false to keep the dialog open.", [launch("Try async save", "dialog-launch-async", showAsync), asyncStatus])
+        ] },
+        { tag: "details", attr: { class: "usage" }, children: [
+            text("summary", "Dialog usage & compatibility"),
+            text("pre", 'DialogComponent.show({\n  header: "Save your changes?",\n  content: "Your workspace has been updated.",\n  footer: { tag: "div", children: [\n    DialogComponent.Cancel(),\n    DialogComponent.Ok(async () => {\n      // Await your save. Return false to keep the dialog open.\n    })\n  ] },\n  showCloseButton: true\n});', "sample-code"),
+            text("p", "Existing options, getRef().open()/close(), and Button/Ok/Cancel helpers are preserved. Width defaults to 32rem and is constrained to the viewport. Height options still size the content area. Empty footers collapse without reserving space."),
+            text("p", "Modal dialogs contain Tab navigation, prevent background scrolling, and restore focus to the opener. Non-modal dialogs leave the background interactive. Escape closes only the top dialog. onClose returning false cancels every close route."),
+            text("p", "The close control is a native button. Use closeButtonLabel to translate its accessible label, or ariaLabel when the header does not provide a suitable dialog name. Dragging and resizing are optional and retain moveOptions and resizeOptions callbacks.")
+        ] }
+    ]
+};

package/examples/showcase/feedback-and-navigation.ts

@@ -0,0 +1,174 @@
+import { IJSLComponent, IJSLVNode, JSLRender } from "jsl-render";
+import { ButtonComponent } from "../../components/button/ButtonComponent";
+import { Notification, NotificationComponent, INotificationOptions } from "../../components/notification/Notification";
+import { LoadingComponent } from "../../components/loading/LoadingComponent";
+import { NavigationComponent } from "../../components/navigation/NavigationComponent";
+
+type Content = IJSLVNode | IJSLComponent;
+const text = (tag: string, content: string, className?: string): IJSLVNode => ({ tag, content, attr: { class: className } });
+const group = (children: Content[], className?: string): IJSLVNode => ({ tag: "div", attr: { class: className }, children });
+const status = (content: string): IJSLVNode => ({ tag: "p", content, attr: { class: "sample-status", role: "status" } });
+const action = (content: string, click: () => void) => new ButtonComponent({ content, click, type: "button", outlined: true, size: "small" });
+function card(id: string, number: string, title: string, description: string, children: Content[]): IJSLVNode {
+    return { tag: "article", attr: { id, class: "sample-card" }, children: [
+        group([text("span", number, "sample-number"), text("h3", title)], "card-heading"),
+        text("p", description, "card-description"), ...children
+    ] };
+}
+function section(id: string, number: string, title: string, description: string, preview: Content, cards: Content[], usage: Content[]): IJSLVNode {
+    return { tag: "section", attr: { id, class: "component-section", "aria-labelledby": id + "-title" }, children: [
+        group([
+            group([text("p", "THE ESSENTIALS / " + number, "eyebrow"),
+                { tag: "h2", content: title, attr: { id: id + "-title", class: "section-title" } },
+                text("p", description, "hero-description")], "hero-copy"),
+            group([text("span", "INTERACTIVE PREVIEW", "preview-caption"), preview], "hero-preview feedback-preview")
+        ], "hero"),
+        group(cards, "sample-grid feedback-sample-grid"),
+        { tag: "details", attr: { class: "usage" }, children: [text("summary", title + " usage & compatibility"), ...usage] }
+    ] };
+}
+const messageStatus = status("Notifications appear in the top-right corner.");
+let latestMessage: string;
+const notify = (options: INotificationOptions) => {
+    latestMessage = Notification.show({ ...options, onClose: () => {
+        messageStatus.content = "Notification dismissed.";
+        options.onClose?.();
+        JSLRender.lastCreatedRenderer?.refresh();
+    } });
+    messageStatus.content = "Notification shown.";
+};
+const variants: INotificationOptions["variant"][] = ["info", "success", "warning", "error"];
+const messages = ["Your export is ready to download.", "All changes have been saved.", "Your session will expire soon.", "We couldn't save your changes. Please try again."];
+export const notificationShowcase = section("notifications", "14", "Notifications",
+    "A little feedback, clearly delivered. Quiet surfaces with a distinct tone for each message.",
+    new NotificationComponent({ title: "Changes saved", content: "Your team is up to date.", variant: "success", closeOnClick: false, showCloseButton: false }), [
+        card("notification-tones", "01", "Feedback with a purpose", "Color supports the message; titles and text explain what happened. Try each live notification.", [
+            group(variants.map((variant, index) => new NotificationComponent({
+                title: ["For your information", "All done", "A quick heads-up", "Something went wrong"][index],
+                content: messages[index], variant, closeOnClick: false, showCloseButton: false
+            })), "notification-samples"),
+            group(variants.map((variant, index) => action("Show " + variant, () => notify({ content: messages[index], variant }))), "sample-row")
+        ]),
+        card("notification-actions", "02", "A useful next step", "Keep a rich message open while its controls are used, or close a simple message with a click.", [
+            group([
+                action("Show message", () => notify({ title: "A new update", content: "Click this message or its close button to dismiss it." })),
+                action("Show action", () => {
+                    const id = Notification.show({
+                    title: "Item archived", closeOnClick: false, content: group([
+                        text("p", "You can restore the item if you change your mind."),
+                        action("Undo archive", () => { Notification.clearNotification(id); messageStatus.content = "Item restored."; JSLRender.lastCreatedRenderer?.refresh(); })
+                    ], "notification-action-copy")
+                    });
+                    latestMessage = id;
+                }),
+                action("Dismiss latest", () => Notification.clearNotification(latestMessage)),
+                action("Dismiss all", () => Notification.clearAll())
+            ], "sample-row"), messageStatus,
+            text("pre", 'const id = Notification.show({\n  title: "Changes saved", content: "Your team is up to date.",\n  variant: "success", closeOnClick: false\n});\nNotification.clearNotification(id);', "sample-code")
+        ]),
+        card("notification-timing", "03", "Time to read", "A countdown bar shows the remaining time. Both the bar and timer pause while hovered or focused. Persistent messages stay until dismissed.", [
+            group([
+                action("Show for 3 seconds", () => notify({ title: "Export complete", content: "Hover or focus this message to pause its timer.", timeOut: 3000, variant: "info" })),
+                action("Show persistent message", () => notify({ title: "Review needed", content: "This message stays open until you dismiss it.", closeOnClick: false, variant: "warning" }))
+            ], "sample-row")
+        ])
+    ], [
+        text("p", "Notification.show(), clearNotification(), clearAll(), content, timeOut, closeOnClick, class, style, and onClick remain available. Messages still close when clicked by default. timeOut defaults to zero (persistent)."),
+        text("p", "Add title, variant, showCloseButton, closeButtonLabel, or onClose. NotificationComponent uses the same surface inline. Informational messages use role=status; warning and error messages use role=alert. Motion follows the user's reduced-motion preference.")
+    ]);
+
+class LoadingDemo implements IJSLComponent {
+    public State = { busy: false, complete: false };
+    private renderer: JSLRender;
+    private timer: ReturnType<typeof setTimeout>;
+    public onInit(renderer: JSLRender) { this.renderer = renderer; }
+    public onRemove() { clearTimeout(this.timer); }
+    public render(): IJSLVNode {
+        return group([
+            new ButtonComponent({ content: this.State.busy ? "Loading report…" : "Load report", enabled: !this.State.busy, type: "button", click: () => {
+                this.State.busy = true; this.State.complete = false;
+                this.timer = setTimeout(() => { this.State.busy = false; this.State.complete = true; this.renderer.refresh(); }, 1800);
+            } }),
+            { tag: "div", attr: { class: "loading-demo-panel", "aria-busy": String(this.State.busy) }, children: [
+                this.State.busy ? new LoadingComponent({ sizeInRem: 1.25, label: "Fetching your report…", showLabel: true }) :
+                    text("p", this.State.complete ? "Your report is ready. 24 projects, all up to date." : "Load a report to try a brief loading state.")
+            ] }
+        ], "loading-demo");
+    }
+}
+export const loadingShowcase = section("loading", "15", "Loading",
+    "A small sign that work is happening. Theme-aware indicators with room for helpful context.",
+    new LoadingComponent({ sizeInRem: 1.5, label: "Getting things ready…", showLabel: true }), [
+        card("loading-sizes", "01", "From inline to centre stage", "The original numeric constructor still sets the ring's size in rem.", [
+            group([1, 2, 3].map(size => group([new LoadingComponent(size), text("span", size + " rem", "size-caption")], "size-sample")), "sample-row size-row"),
+            text("pre", 'new LoadingComponent(1);\nnew LoadingComponent(3);', "sample-code")
+        ]),
+        card("loading-labels", "02", "Say what's happening", "Provide a useful label when a task takes time. Labels remain accessible when visually hidden.", [
+            group([
+                new LoadingComponent({ sizeInRem: 1, label: "Saving changes…", showLabel: true }),
+                new LoadingComponent({ sizeInRem: 1.5, label: "Syncing files…", showLabel: true, style: "--jsl-loading-color:var(--jsl-color-success)" })
+            ], "loading-label-samples"),
+            text("pre", '{ sizeInRem: 1, label: "Saving changes…", showLabel: true }', "sample-code")
+        ]),
+        card("loading-workflow", "03", "A moment between states", "Disable a repeated action while it runs, and mark the affected region as busy.", [new LoadingDemo()])
+    ], [
+        text("p", "The numeric constructor and its original 6 rem default remain available. An options object adds sizeInRem, label, showLabel, class, and style. The ring uses the current theme's accent; override --jsl-loading-color for a particular context."),
+        text("p", "Each indicator has an accessible status label. Use aria-busy on the region being updated. Reduced-motion mode keeps the ring visible without rotating it.")
+    ]);
+
+const navStatus = status("Choose a destination or an action.");
+const selected = (name: string) => () => { navStatus.content = "Selected: " + name + "."; };
+const wideNavigation = new NavigationComponent({
+    title: "Workspace", position: "default", alignment: "right", ariaLabel: "Workspace example",
+    data: [
+        { content: "Overview", link: "#navigation", click: selected("Overview") },
+        { content: "Projects", link: "#navigation/projects", click: selected("Projects"), children: [
+            { content: "All projects", link: "#navigation/projects/all", click: selected("All projects") },
+            { content: "Create project", click: selected("Create project") },
+            { content: "Templates", children: [
+                { content: "Design review", click: selected("Design review") },
+                { content: "Sprint planning", click: selected("Sprint planning") }
+            ] }
+        ] },
+        { content: "Resources", children: [
+            { content: "Documentation", link: "https://example.com", target: "_blank" },
+            { content: "What's new", click: selected("What's new") }
+        ] },
+        { content: "Admin", enabled: false, click: selected("Admin") }
+    ]
+});
+const compactNavigation = new NavigationComponent({ title: "Team space", position: "static", ariaLabel: "Compact example", data: [
+    { content: "Activity", active: true, click: selected("Activity") },
+    { content: "People", click: selected("People") },
+    { content: "Settings", children: [
+        { content: "Profile", click: selected("Profile") },
+        { content: "Notifications", click: selected("Notification settings") }
+    ] }
+] });
+export const navigationShowcase = section("navigation", "16", "Navigation",
+    "A clear way through. Familiar links, purposeful actions, and menus that work at any size.",
+    group([new NavigationComponent({ title: "Studio", position: "default", ariaLabel: "Navigation preview", data: [
+        { content: "Projects", active: true, click: selected("Projects") },
+        { content: "Team", click: selected("Team") }
+    ] })], "navigation-preview"), [
+        card("navigation-bar", "01", "A place for everything", "Follow a link, open a submenu, or run an action. Project links and their adjacent submenu buttons work independently.", [
+            wideNavigation, navStatus,
+            text("p", "Try Tab, Enter or Space, arrow keys, and Escape. Click outside a menu to close it.", "inline-note")
+        ]),
+        card("navigation-compact", "02", "Comfortable in a smaller space", "Navigation adapts to its container as well as the viewport. Open the menu to explore its destinations.", [
+            group([compactNavigation], "navigation-compact-sample"),
+            text("pre", '{ title: "Team space", position: "static", data }', "sample-code")
+        ]),
+        card("navigation-markup", "03", "Your content, your destinations", "A brand and each item can contain a VNode. Native anchors preserve standard browser behavior, including opening links in another tab.", [
+            new NavigationComponent({
+                title: group([text("span", "S", "navigation-brand-mark"), text("span", "Studio")], "navigation-rich-brand"),
+                titleLink: "#navigation", position: "default", ariaLabel: "Rich content example",
+                data: [{ content: "Home", link: "#navigation" }, { content: "Help", click: selected("Help") }]
+            })
+        ])
+    ], [
+        text("pre", 'new NavigationComponent({\n  title: "Workspace", position: "default", alignment: "right",\n  data: [\n    { content: "Overview", link: "#overview" },\n    { content: "Projects", children: [\n      { content: "Create project", click: () => createProject() }\n    ] }\n  ]\n});', "sample-code"),
+        text("p", "The existing title, titleLink, data, link, target, click, alignment, position, class, style, and id options remain. New options include ariaLabel, menuButtonLabel, activeLink, and item active, enabled, submenuLabel, and nested children."),
+        text("p", "Navigation is rebuilt without Luxbar. Custom CSS that targets old Luxbar classes must be updated. id now identifies the header; menu and submenu IDs are derived from it (or generated uniquely). Items without links use buttons, and the title is plain text unless titleLink is provided."),
+        text("p", "default and static participate in normal document flow. fixed (the original default) and fixed-bottom attach to the viewport. Active links follow hashchange and popstate, with path boundaries respected; activeLink or item.active can override route detection. Menus close when focus leaves, on outside interaction, on selection, or with Escape.")
+    ]);