jsl-ui 9.28.7 → 10.0.0

package/examples/showcase/fields.ts

@@ -0,0 +1,178 @@
+import { IJSLComponent, IJSLVNode } from "jsl-render";
+import { InputComponent } from "../../components/input/InputComponent";
+import { NumberComponent } from "../../components/number/NumberComponent";
+import { DateComponent } from "../../components/date/DateComponent";
+import { SelectComponent } from "../../components/select/SelectComponent";
+import { FormFieldComponent } from "../../components/form-field/FormFieldComponent";
+import { FormComponent } from "../../components/form-field/FormComponent";
+import { ButtonComponent } from "../../components/button/ButtonComponent";
+import { date } from "../../core/date";
+import { numeric } from "../../core/numeric";
+
+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" });
+const sampleField = (id: string, label: string, control: Content) => group([
+    { tag: "label", content: label, attr: { for: id } }, control
+], "field-sample");
+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: 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 fields-preview")
+        ], "hero"),
+        group(cards, "sample-grid fields-sample-grid"),
+        { tag: "details", attr: { class: "usage" }, children: [text("summary", title + " usage & compatibility"), ...usage] }
+    ] };
+}
+const inputStatus = status("Start typing to see the input event.");
+const textModel = { notes: "A few notes for the team." };
+const textStatus = status("26 characters in the model.");
+export const inputShowcase = section("inputs", "11", "Inputs",
+    "A consistent place to type. Simple defaults for text, passwords, and longer notes.",
+    new InputComponent({ id: "input-preview", placeholder: "What are you working on?", ariaLabel: "Preview input" }), [
+        card("input-basic", "01", "Text as you type", "Input and change events keep their familiar string values. Add an external label or use a FormField.", [
+            sampleField("input-name", "Project name", new InputComponent({
+                id: "input-name", placeholder: "Give your project a name", maxLength: 40,
+                onInput: value => { inputStatus.content = value ? "Typing: " + value : "The field is empty."; },
+                onChange: value => { inputStatus.content = "Committed: " + (value || "empty"); }
+            })), inputStatus
+        ]),
+        card("input-textarea", "02", "Room for a longer thought", "The same component supports a textarea, including binding on every input event.", [
+            sampleField("input-notes", "Notes", new InputComponent({
+                id: "input-notes", type: "textarea", rows: 4,
+                bindTo: textModel, property: "notes", bindMode: "both", bindOnInput: true,
+                onInput: () => { textStatus.content = textModel.notes.length + " characters in the model."; }
+            })), textStatus
+        ]),
+        card("input-states", "03", "Useful native input types", "Passwords, email, read-only values, and disabled fields share the same base appearance.", [
+            sampleField("input-password", "Password", new InputComponent({ id: "input-password", type: "password", value: "A little privacy" })),
+            sampleField("input-readonly", "Read-only identifier", new InputComponent({ id: "input-readonly", value: "PROJ-2026-010", readOnly: true })),
+            sampleField("input-disabled", "Unavailable value", new InputComponent({ id: "input-disabled", value: "Managed by your team", enabled: false }))
+        ]),
+        card("input-unstyled", "04", "A building block when needed", "Opt out of the library surface for a grid cell or a custom editor. Behavior and binding remain available.", [
+            group([
+                text("span", "PROJECT /", "inline-note"),
+                new InputComponent({ id: "input-plain", value: "An inline title", ariaLabel: "Inline title", unstyled: true, class: "showcase-inline-input" })
+            ], "unstyled-input-sample"),
+            text("pre", '{ unstyled: true, class: "my-editor" }', "sample-code")
+        ])
+    ], [
+        text("pre", 'new InputComponent({\n  value: "A project", placeholder: "Project name",\n  bindTo: model, property: "name", bindMode: "both",\n  onChange: value => console.log(value)\n});', "sample-code"),
+        text("p", "Existing options, events, binding, converters, getValue(), and setValue() remain supported. The input alias for type is retained. setValue() stays silent. unstyled skips the base CSS class; ariaLabel, readOnly, rows, autocomplete, and focus() are optional additions."),
+        text("p", "bindOnInput now works even without an onInput subscriber. Two-way bindings preserve a draft until the model actually changes, including the caret in a textarea.")
+    ]);
+
+const numberStatus = status("Commit a value with Enter or by leaving the field.");
+const moneyModel = { cents: 12500 };
+const moneyStatus = status("Model value: 12500 cents");
+export const numberShowcase = section("numbers", "12", "Numbers",
+    "The same surface, with numeric behavior. Formats and converters stay close to the value.",
+    new NumberComponent({ id: "number-preview", value: 1250.5, format: "#,0.00", ariaLabel: "Preview amount" }), [
+        card("number-basic", "01", "A number with a format", "Edit a decimal, then commit it. Formatting happens on blur or Enter.", [
+            sampleField("number-amount", "Amount", new NumberComponent({
+                id: "number-amount", value: 1250.5, format: "#,0.00",
+                onChange: value => { numberStatus.content = value == null ? "Amount cleared." : "Numeric value: " + value; }
+            })), numberStatus,
+            sampleField("number-zero", "Whole number", new NumberComponent({ id: "number-zero", value: 0, format: "0" }))
+        ]),
+        card("number-binding", "02", "One value, two representations", "A converter presents cents as a decimal amount and converts committed edits back to cents.", [
+            sampleField("number-cents", "Budget", new NumberComponent({
+                id: "number-cents", bindTo: moneyModel, property: "cents", bindMode: "both", format: "0.00",
+                converter: { toUI: value => value / 100, toData: value => value == null ? null : Math.round(value * 100) },
+                onChange: () => { moneyStatus.content = "Model value: " + moneyModel.cents + " cents"; }
+            })), moneyStatus,
+            action("Set budget to 250.00", () => { moneyModel.cents = 25000; moneyStatus.content = "Model value: 25000 cents"; })
+        ]),
+        card("number-options", "03", "Choose when to format", "Formatting and Enter commits can be disabled independently.", [
+            sampleField("number-live", "Format preserved while editing", new NumberComponent({
+                id: "number-live", value: 12.5, format: "0.00", formatOnBlur: false, commitOnEnter: false
+            })),
+            text("pre", "{ formatOnBlur: false, commitOnEnter: false }", "sample-code")
+        ]),
+        card("number-states", "04", "Consistent states", "Disabled and read-only values match the other controls. Unstyled mode remains available for embedded editors.", [
+            sampleField("number-disabled", "Unavailable amount", new NumberComponent({ id: "number-disabled", value: 99, format: "0.00", enabled: false })),
+            sampleField("number-readonly", "Calculated total", new NumberComponent({ id: "number-readonly", value: 149.95, format: "0.00", readOnly: true })),
+            text("pre", '{ unstyled: true }', "sample-code")
+        ])
+    ], [
+        text("pre", 'new NumberComponent({\n  value: 1250.5, format: "#,0.00",\n  onChange: value => console.log(value)\n});', "sample-code"),
+        text("p", "getValue() returns the displayed string; getValueAsNumber() returns its parsed number. Formatting follows the existing culture settings and numeric helpers. Empty values remain undefined. setValue() updates writable bindings silently."),
+        text("p", "commitOnEnter is now honored. Enter followed by blur does not publish the same commit twice. Malformed numeric drafts remain visible for correction and do not write NaN to the model.")
+    ]);
+
+const projectOptions = [{ value: "design", text: "Design system" }, { value: "website", text: "Website refresh" }, { value: "research", text: "Customer research" }];
+const cities = ["Vienna", "Berlin", "Copenhagen", "London", "New York", "Singapore", "Sydney", "Tokyo"];
+const validationStatus = status("Validate the form to see messages below its controls.");
+const emailField = new FormFieldComponent({
+    label: "Email address", required: true, description: "Use your work email.",
+    control: new InputComponent({ id: "field-email", type: "email", placeholder: "you@example.com" })
+});
+const projectField = new FormFieldComponent({
+    label: "Project", required: true,
+    control: new SelectComponent({ id: "field-project", data: projectOptions, placeholder: "Choose a project" })
+});
+const validationForm = new FormComponent([emailField, projectField, action("Validate form", () => {
+    validationStatus.content = validationForm.validate() ? "All fields are valid." : "Please correct the marked fields.";
+}), validationStatus]);
+
+export const formFieldShowcase = section("form-fields", "13", "Form fields",
+    "A label and a little guidance. Wrap the control that fits the job.",
+    new FormFieldComponent({
+        label: "Project name", description: "Clear names help everyone find their work.",
+        control: new InputComponent({ id: "field-preview", value: "Component library" })
+    }), [
+        card("field-composition", "01", "Controls that belong together", "Text, numbers, and selects keep their own behavior while sharing a consistent field layout.", [
+            group([
+                new FormFieldComponent({ label: "Project name", control: new InputComponent({ id: "field-name", value: "A new project" }) }),
+                new FormFieldComponent({ label: "Budget", control: new NumberComponent({ id: "field-budget", value: 1200, format: "#,0.00" }) }),
+                new FormFieldComponent({ label: "Team", control: new SelectComponent({ id: "field-team", data: projectOptions, value: "design" }) })
+            ], "composed-fields"),
+            text("pre", 'new FormFieldComponent({\n  label: "Team", control: new SelectComponent({ data })\n});', "sample-code")
+        ]),
+        card("field-legacy", "02", "Existing field types still work", "The original shorthand creates the same input components internally. Existing getValue(), setValue(), and validation calls continue to work.", [
+            new FormFieldComponent({ id: "field-legacy-text", label: "User name", type: "text", value: "Alex" }),
+            new FormFieldComponent({ id: "field-legacy-password", label: "Password", type: "password", value: "A private value" }),
+            text("pre", 'new FormFieldComponent({ label: "User name", type: "text" });', "sample-code")
+        ]),
+        card("field-specialized", "03", "Dates and formatted numbers", "Specialized controls handle their values and popups. The field adds the label and supporting text.", [
+            new FormFieldComponent({
+                id: "field-date", label: "Start date", type: "date", value: "15/10/2026",
+                dateOptions: { format: value => date.format(value, "dd/mm/yy"), parse: value => date.parse(value, "dd/mm/yy") }
+            }),
+            new FormFieldComponent({ id: "field-number", label: "Estimated cost", type: "number", value: numeric.format(1250.5, "0.00"), numberOptions: { format: "#,0.00" } }),
+            new FormFieldComponent({ label: "Milestone", control: new DateComponent({ id: "field-wrapped-date", value: new Date(2026, 9, 21) }) })
+        ]),
+        card("field-autosuggest", "04", "Suggestions while you type", "AutoSuggestComponent now uses the shared input styling and owns its suggestion lifecycle.", [
+            new FormFieldComponent({
+                id: "field-city", label: "Office city", type: "autosuggest", placeholder: "Start typing a city",
+                description: "Try Vienna, Berlin, or Tokyo.",
+                autoSuggestOptions: { minChars: 1, delay: 0, source: (term, suggest) => suggest(cities.filter(city => city.toLowerCase().includes(term.toLowerCase()))) }
+            }),
+            text("p", "The original autoSuggestOptions source and callbacks remain available.", "inline-note")
+        ]),
+        card("field-validation", "05", "Guidance near the control", "Required and custom validation messages appear separately from the label and are associated with the control.", [
+            validationForm
+        ]),
+        card("field-layout", "06", "An optional floating label", "Keep labels above controls by default, or place them on the outline. Disabled fields disable their wrapped native controls.", [
+            new FormFieldComponent({ id: "field-floating", label: "Workspace", labelPosition: "floating", value: "Design workspace", description: "The label stays visible when the field is empty." }),
+            new FormFieldComponent({ label: "Managed project", disabled: true, control: new SelectComponent({ id: "field-disabled-select", data: projectOptions, value: "design" }) }),
+            new FormFieldComponent({ id: "field-disabled-input", label: "Managed identifier", disabled: true, value: "PROJ-2026-010" })
+        ])
+    ], [
+        text("pre", 'const input = new InputComponent({ bindTo: model, property: "name", bindMode: "both" });\nconst field = new FormFieldComponent({\n  label: "Project name", control: input,\n  description: "Choose a name your team will recognize.",\n  required: true\n});', "sample-code"),
+        text("p", "FormField owns labels, layout, descriptions, required indicators, and validation feedback. The child owns editing, formatting, binding, and popup cleanup. Supply control to compose an existing component; legacy type, value, dateOptions, numberOptions, and autoSuggestOptions use a compatibility factory."),
+        text("p", "getValue() and setValue() delegate to the wrapped control, so supplied controls use their own setter types (for example, a number or Date). Legacy number and date fields continue to accept string values. getControl() returns the child component. A generic return type can describe custom controls, for example FormFieldComponent<string[]> for a multi-select."),
+        text("p", "A native label targets the wrapped control's existing ID. id or controlId can specify the target. Helper and validation messages extend existing aria-describedby associations. disabled uses a native fieldset so controls such as SelectComponent are disabled together."),
+        text("p", "The default labelPosition is above. The optional floating presentation places an always-visible label on the outline, preserving space for a placeholder. Custom controls keep their own surfaces.")
+    ]);

package/examples/showcase/fonts/OFL-Jost.txt

@@ -0,0 +1,93 @@
+Copyright 2020 The Jost Project Authors (https://github.com/indestructible-type)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/examples/showcase/grids.ts

@@ -0,0 +1,150 @@
+import { IJSLVNode, JSLRender } from "jsl-render";
+import { GridComponent } from "../../components/grid/GridComponent";
+import { ISlickColumn } from "../../grid/slick.core";
+import { TextEditor, NumericEditor, BooleanEditor } from "../../grid/slick.editors.core";
+import { DateEditor } from "../../grid/slick.editors.date";
+import { DateFormatter, NumericFormatter, CheckboxFormatter } from "../../grid/slick.formatters";
+import { ButtonComponent } from "../../components/button/ButtonComponent";
+import { numeric } from "../../core/numeric";
+
+interface Project { id: number; name: string; team: string; budget: number; date: Date; approved: boolean; }
+function data(count: number): Project[] {
+    const names = ["Design system", "Website refresh", "Customer research", "Mobile workspace", "Reporting tools"];
+    return Array.from({ length: count }, (_, index) => ({
+        id: index + 1, name: names[index % names.length] + " " + (index + 1),
+        team: ["Design", "Engineering", "Operations"][index % 3], budget: 1500 + index * 125,
+        date: new Date(2026, 9, 1 + index % 28), approved: index % 3 !== 0
+    }));
+}
+function columns(editable = false): ISlickColumn[] {
+    return [
+        { id: "id", name: "ID", width: 65, sortable: true },
+        { id: "name", name: "Project", width: 250, sortable: true, editor: editable ? TextEditor : undefined },
+        { id: "team", name: "Team", width: 145, sortable: true, editor: editable ? TextEditor : undefined },
+        { id: "budget", name: "Budget", width: 125, sortable: true, headerCssClass: "right", formatter: NumericFormatter, format: "#,0", editor: editable ? NumericEditor : undefined },
+        { id: "date", name: "Start date", width: 135, sortable: true, formatter: DateFormatter, editor: editable ? DateEditor : undefined },
+        { id: "approved", name: "Approved", width: 100, headerCssClass: "center", formatter: CheckboxFormatter, editor: editable ? BooleanEditor : undefined }
+    ];
+}
+const text = (tag: string, content: string): IJSLVNode => ({ tag, content });
+const action = (content: string, click: () => void) => new ButtonComponent({ content, click, type: "button", outlined: true, size: "small" });
+function card<T>(id: string, title: string, description: string, grid: GridComponent<T>, extras: any[] = []): IJSLVNode {
+    return { tag: "article", attr: { id, class: "sample-card grid-sample-card" }, children: [
+        text("h3", title), { tag: "p", content: description, attr: { class: "card-description" } },
+        ...extras, { tag: "div", attr: { class: "grid-sample-host" }, children: [grid] }
+    ] };
+}
+const basic = new GridComponent(data(30), columns(), {
+    primaryKey: "id", multiColumnSort: true, numberedMultiColumnSort: true
+}, "300px");
+const edits: IJSLVNode = { tag: "p", content: "Edit a project, budget, date, or approval value.", attr: { role: "status", class: "sample-status" } };
+const editable = new GridComponent(data(25), columns(true), { primaryKey: "id", editable: true, autoEdit: false }, "300px");
+editable.initEvents(grid => grid.onAfterEdit.subscribe((_event, args) => {
+    edits.content = "Updated " + args.column.name + " for project " + args.item.id + ".";
+    // Grid events run independently of the showcase renderer.
+    JSLRender.lastCreatedRenderer?.refresh();
+}));
+const grouped = new GridComponent(data(45), columns(), { primaryKey: "id" }, "320px");
+grouped.initEvents(grid => grid.dataView.setGrouping({
+    getter: "team", formatter: group => group.value + " · " + group.count + " projects", aggregators: [], displayTotalsRow: false
+}));
+const frozenData = data(120).map((project, index) => ({
+    ...project,
+    owner: ["Alex Morgan", "Sam Weber", "Jordan Lee", "Robin Taylor"][index % 4],
+    status: ["Planning", "In progress", "In review", "Complete"][index % 4],
+    due: new Date(2026, 11, 1 + index % 28),
+    plannedHours: 80 + index * 4,
+    actualHours: 25 + index * 3,
+    location: ["Vienna", "London", "Berlin", "New York"][index % 4]
+}));
+const frozenColumns: ISlickColumn[] = [
+    ...columns().map(column => ({ ...column, width: column.id === "name" ? 300 : 180 })),
+    { id: "owner", name: "Project owner", width: 200, sortable: true },
+    { id: "status", name: "Status", width: 180, sortable: true },
+    { id: "due", name: "Due date", width: 180, sortable: true, formatter: DateFormatter },
+    { id: "plannedHours", name: "Planned hours", width: 180, sortable: true, headerCssClass: "right", formatter: NumericFormatter, format: "#,0" },
+    { id: "actualHours", name: "Actual hours", width: 180, sortable: true, headerCssClass: "right", formatter: NumericFormatter, format: "#,0" },
+    { id: "location", name: "Office", width: 180, sortable: true }
+];
+const frozen = new GridComponent(frozenData, frozenColumns, {
+    primaryKey: "id", frozenColumn: 1
+}, "320px");
+const large = new GridComponent(data(10000), columns(), { primaryKey: "id", rowHeight: 28 }, "320px");
+
+const costingData = data(12).map((project, index) => ({
+    ...project, hours: 16 + index * 4, rate: 85 + index % 3 * 15, cost: 0
+}));
+const costingColumns: ISlickColumn[] = [
+    { id: "id", name: "ID", width: 65, columnGroup: "Project" },
+    { id: "name", name: "Project", width: 240, columnGroup: "Project", editor: TextEditor },
+    { id: "team", name: "Team", width: 140, columnGroup: "Project" },
+    { id: "hours", name: "Hours", width: 120, columnGroup: "Costing", headerCssClass: "right", formatter: NumericFormatter, format: "#,0.00", editor: NumericEditor },
+    { id: "rate", name: "Hourly rate", width: 135, columnGroup: "Costing", headerCssClass: "right", formatter: NumericFormatter, format: "#,0.00", editor: NumericEditor },
+    { id: "cost", name: "Estimated cost", width: 160, columnGroup: "Costing", headerCssClass: "right", formatter: NumericFormatter, format: "#,0.00", readonly: true, toolTip: "Calculated: hours × hourly rate" },
+    { id: "date", name: "Start date", width: 140, columnGroup: "Schedule", formatter: DateFormatter }
+];
+const costing = new GridComponent(costingData, costingColumns, {
+    primaryKey: "id", editable: true, autoEdit: false, showColumnGroups: true,
+    preHeaderPanelHeight: 37, createFooterRow: true, showFooterRow: true, footerRowHeight: 36,
+    enableColumnReorder: false
+}, "380px");
+costing.initEvents(grid => {
+    grid.addFormula("cost", item => (item.hours || 0) * (item.rate || 0), ["hours", "rate"]);
+    grid.triggerAllFormulas();
+    const updateTotals = () => {
+        const label = grid.getFooterRowColumn("name");
+        if (label) { label.textContent = "Total"; }
+        for (const field of ["hours", "cost"] as const) {
+            const footer = grid.getFooterRowColumn(field);
+            if (footer) {
+                footer.classList.add("right", "tabular-nums");
+                footer.textContent = numeric.format(grid.getData().reduce((sum, item) => sum + item[field], 0), "#,0.00");
+            }
+        }
+    };
+    grid.onAfterEdit.subscribe(updateTotals);
+    grid.onFooterRowCellRendered.subscribe(updateTotals);
+    updateTotals();
+});
+
+const orderStatus: IJSLVNode = { tag: "p", content: "Drag a handle to change the project order.", attr: { role: "status", class: "sample-status" } };
+const reorder = new GridComponent(data(15), [
+    { id: "_move", name: "", width: 36, minWidth: 36, maxWidth: 36, resizable: false, selectable: false,
+        behavior: "selectAndMove", cssClass: "grid-row-handle", toolTip: "Drag to reorder", formatter: () => '<span aria-hidden="true">⠿</span>' },
+    { id: "priority", name: "Order", width: 75, headerCssClass: "center", formatter: row => ({ text: String(row + 1), addClasses: ["center", "tabular-nums"] }) },
+    ...columns().filter(column => column.id !== "id").map(column => ({ ...column, sortable: false }))
+], { primaryKey: "id", allowRowMove: true, enableColumnReorder: false }, "320px");
+reorder.initEvents(grid => grid.dataView.onRowsChanged.subscribe(() => {
+    orderStatus.content = "Project order: " + grid.getData().map(item => item.id).join(", ") + ".";
+    JSLRender.lastCreatedRenderer?.refresh();
+}));
+export const gridShowcase: IJSLVNode = {
+    tag: "section", attr: { id: "grids", class: "component-section", "aria-labelledby": "grids-title" }, children: [
+        { tag: "div", attr: { class: "hero-copy" }, children: [
+            { tag: "p", content: "THE ESSENTIALS / 22", attr: { class: "eyebrow" } },
+            { tag: "h2", content: "Grids", attr: { id: "grids-title", class: "section-title" } },
+            text("p", "Representative data, editing, grouping, and scrolling examples for the grid redesign.")
+        ] },
+        { tag: "div", attr: { class: "grid-samples" }, children: [
+            card("grid-basic", "Browse and sort", "30 projects. Click a heading to sort, then Shift-click other headings to add sort levels. Numbers show sorting priority. Select rows and resize or reorder columns.", basic),
+            card("grid-editable", "Edit in place", "Double-click an editable cell or press F2. Enter commits and Escape cancels. Editors retain their existing behavior and styling in this step.", editable, [edits]),
+            card("grid-grouped", "Grouped projects", "45 projects grouped by team. Expand and collapse groups independently.", grouped, [
+                { tag: "div", attr: { class: "sample-row" }, children: [
+                    action("Collapse groups", () => { grouped.getRef().then(grid => grid.dataView.collapseAllGroups()); }),
+                    action("Expand groups", () => { grouped.getRef().then(grid => grid.dataView.expandAllGroups()); })
+                ] }
+            ]),
+            card("grid-frozen", "Frozen columns", "12 columns and 120 projects. The ID and project stay visible while you scroll through ownership, status, dates, hours, and office details, even on wide screens.", frozen),
+            card("grid-large", "A larger dataset", "10,000 rows with an explicit rowHeight of 28 px. This example also checks that applications can retain the original density.", large),
+            card("grid-costing", "Column groups, formulas & totals", "Project, Costing, and Schedule headers group related columns. Double-click Hours or Hourly rate to edit: the grid formula recalculates Estimated cost, and the footer updates the totals.", costing, [
+                { tag: "pre", content: 'grid.addFormula("cost", item => item.hours * item.rate, ["hours", "rate"]);', attr: { class: "sample-code" } }
+            ]),
+            card("grid-reorder", "Arrange project priorities", "Drag a handle in the first column to move a project. The Order column follows its position while project IDs remain unchanged. Sorting is disabled here so it does not override the manual order.", reorder, [orderStatus])
+        ] },
+        { tag: "details", attr: { class: "usage" }, children: [
+            text("summary", "Grid showcase scope"),
+            text("p", 'NumericFormatter supplies right-aligned cells; NumericFormatter and DateFormatter apply tabular numerals. Set headerCssClass: "right" or "center" explicitly to match a column’s content. Header alignment is never inferred from its formatter.'),
+            text("p", "These examples use the existing GridComponent constructor, column definitions, editors, and DataView APIs. The default row height is 36 px; rowHeight can retain a different density. Core presentation follows the shared theme and inherits the host's typography. Editors, filter dialogs, menus, and lifecycle behavior are reserved for later steps.")
+        ] }
+    ]
+};

package/examples/showcase/index.html

@@ -0,0 +1,60 @@
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta name="description" content="An interactive showcase of the redesigned JSL UI components.">
+  <title>JSL UI Showcase</title>
+  <link rel="stylesheet" href="./showcase.css">
+</head>
+<body>
+  <a class="skip-link" href="#main">Skip to components</a>
+  <aside class="sidebar" aria-label="Component navigation">
+    <a class="brand" href="#main"><span class="brand-mark">j.</span><span>JSL UI<span class="brand-caption">Component showcase</span></span></a>
+    <p class="nav-label">COMPONENTS <span>22</span></p>
+    <nav>
+      <a class="nav-item" href="#buttons" aria-current="location"><span class="nav-icon" aria-hidden="true">▣</span> Buttons <span class="nav-number">01</span></a>
+      <a class="nav-item" href="#dialogs"><span class="nav-icon" aria-hidden="true">▢</span> Dialogs <span class="nav-number">02</span></a>
+      <a class="nav-item" href="#tabs"><span class="nav-icon" aria-hidden="true">▤</span> Tabs <span class="nav-number">03</span></a>
+      <a class="nav-item" href="#sliders"><span class="nav-icon" aria-hidden="true">↔</span> Sliders <span class="nav-number">04</span></a>
+      <a class="nav-item" href="#dates"><span class="nav-icon" aria-hidden="true">▦</span> Dates <span class="nav-number">05</span></a>
+      <a class="nav-item" href="#date-ranges"><span class="nav-icon" aria-hidden="true">↔</span> Date ranges <span class="nav-number">06</span></a>
+      <a class="nav-item" href="#date-times"><span class="nav-icon" aria-hidden="true">◷</span> Date &amp; time <span class="nav-number">07</span></a>
+      <a class="nav-item" href="#selects"><span class="nav-icon" aria-hidden="true">⌄</span> Selects <span class="nav-number">08</span></a>
+      <a class="nav-item" href="#checkboxes"><span class="nav-icon" aria-hidden="true">☑</span> Checkboxes <span class="nav-number">09</span></a>
+      <a class="nav-item" href="#expanders"><span class="nav-icon" aria-hidden="true">›</span> Expanders <span class="nav-number">10</span></a>
+      <a class="nav-item" href="#inputs"><span class="nav-icon" aria-hidden="true">⌨</span> Inputs <span class="nav-number">11</span></a>
+      <a class="nav-item" href="#numbers"><span class="nav-icon" aria-hidden="true">#</span> Numbers <span class="nav-number">12</span></a>
+      <a class="nav-item" href="#form-fields"><span class="nav-icon" aria-hidden="true">▤</span> Form fields <span class="nav-number">13</span></a>
+      <a class="nav-item" href="#notifications"><span class="nav-icon" aria-hidden="true">!</span> Notifications <span class="nav-number">14</span></a>
+      <a class="nav-item" href="#loading"><span class="nav-icon" aria-hidden="true">◌</span> Loading <span class="nav-number">15</span></a>
+      <a class="nav-item" href="#navigation"><span class="nav-icon" aria-hidden="true">☰</span> Navigation <span class="nav-number">16</span></a>
+      <a class="nav-item" href="#progress"><span class="nav-icon" aria-hidden="true">&#9648;</span> Progress <span class="nav-number">17</span></a>
+      <a class="nav-item" href="#stack-panels"><span class="nav-icon" aria-hidden="true">&#9707;</span> Stack panels &amp; splitters <span class="nav-number">18</span></a>
+      <a class="nav-item" href="#trees"><span class="nav-icon" aria-hidden="true">&#8627;</span> Tree views <span class="nav-number">19</span></a>
+      <a class="nav-item" href="#overlays"><span class="nav-icon" aria-hidden="true">&#9703;</span> Overlays <span class="nav-number">20</span></a>
+      <a class="nav-item" href="#ribbons"><span class="nav-icon" aria-hidden="true">&#9637;</span> Ribbon menus <span class="nav-number">21</span></a>
+      <a class="nav-item" href="#grids"><span class="nav-icon" aria-hidden="true">&#9638;</span> Grids <span class="nav-number">22</span></a>
+    </nav>
+    <div class="sidebar-note"><span class="status-dot"></span> A growing collection<p>Redesigned components will be added here as the library evolves.</p></div>
+  </aside>
+  <main id="main" tabindex="-1">
+    <div class="page-meta">
+      <span>LIBRARY / COMPONENTS</span>
+      <div class="page-tools">
+        <label class="theme-picker" for="showcase-culture" title="Changing culture reloads and resets the examples with the selected date and number formats.">Culture
+          <select id="showcase-culture"><option value="">Default (ISO)</option></select>
+        </label>
+        <span id="showcase-format-preview" class="format-preview" aria-label="Date and number format example"></span>
+        <label class="theme-picker" for="showcase-theme">Theme
+          <select id="showcase-theme"><option value="default">Default (neutral)</option></select>
+        </label>
+        <span class="version">JSL UI <span class="status-dot"></span> Design preview</span>
+      </div>
+    </div>
+    <div id="showcase"></div>
+    <footer class="page-footer"><span>JSL UI · Component showcase</span><span>Built for everyday work.</span></footer>
+  </main>
+  <script type="module" src="./showcase.ts"></script>
+</body>
+</html>

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

@@ -0,0 +1,47 @@
+import { IJSLComponent, IJSLVNode } from "jsl-render";
+import { ProgressComponent } from "../../components/progress/ProgressComponent";
+import { StackPanelComponent } from "../../components/stack-panel/StackPanelComponent";
+import { SplitterComponent } from "../../components/stack-panel/SplitterComponent";
+import { TreeViewComponent } from "../../components/tree-view/TreeViewComponent";
+import { OverlayComponent } from "../../components/overlay/OverlayComponent";
+import { RibbonMenuComponent } from "../../components/ribbon-menu/RibbonMenuComponent";
+import { ButtonComponent } from "../../components/button/ButtonComponent";
+type Content=IJSLVNode|IJSLComponent;
+const text=(tag:string,content:string):IJSLVNode=>({tag,content});
+const group=(children:Content[],className?:string):IJSLVNode=>({tag:"div",attr:{class:className},children});
+const button=(content:string,click:()=>void)=>new ButtonComponent({content,click,type:"button",outlined:true,size:"small"});
+const panel=(title:string,copy:string)=>group([text("h3",title),text("p",copy)],"layout-demo-panel");
+function section(id:string,number:string,title:string,copy:string,children:Content[],usage:string):IJSLVNode {
+    return {tag:"section",attr:{id,class:"component-section","aria-labelledby":id+"-title"},children:[
+        group([text("p","THE ESSENTIALS / "+number),{tag:"h2",content:title,attr:{id:id+"-title",class:"section-title"}},text("p",copy)],"hero-copy"),
+        group(children,"sample-card remaining-demo"),
+        {tag:"details",attr:{class:"usage"},children:[text("summary",title+" usage & compatibility"),text("p",usage)]}
+    ]};
+}
+const progress=new ProgressComponent(45,{showPercent:true,ariaLabel:"Upload progress"});
+export const progressShowcase=section("progress","17","Progress","A clear measure of how far a task has come.",[
+    progress,group([button("Advance",()=>progress.setProgress(Math.min(100,progress.getProgress()+10))),button("Reset",()=>progress.setProgress(0))],"sample-row"),
+    new ProgressComponent(72,{ariaLabel:"Processing progress"}),text("p","A slim indicator without a percentage label.")
+],"The numeric constructor, color override, formatting, getProgress(), and setProgress() remain available. Displayed values are clamped to 0–100. ariaLabel names the progress bar.");
+export const stackShowcase=section("stack-panels","18","Stack panels & splitters","Comfortable layouts with a small, precise resize handle.",[
+    text("h3","Side by side"),new StackPanelComponent([panel("Library","Drag the handle or focus it and use the arrow keys."),new SplitterComponent({minSizesInPX:[90,90]}),panel("Workspace","Shift + arrow moves faster. Home and End move to the allowed limits.")],{sizes:["40%",undefined,"*"],style:"height:220px;border:1px solid var(--jsl-color-border);border-radius:.5rem;overflow:hidden"}),
+    text("h3","One above another"),new StackPanelComponent([panel("Preview","Vertical layouts resize by height."),new SplitterComponent({minSizesInPX:[60,60]}),panel("Details","The completion callback reports the first panel's height in this layout.")],{orientation:"vertical",sizes:["45%",undefined,"*"],style:"height:300px;border:1px solid var(--jsl-color-border);border-radius:.5rem;overflow:hidden"}),
+    text("h3","Responsive layout"),new StackPanelComponent([panel("First","Panels stack on smaller screens."),panel("Second","No resize handle is needed here.")],{responsive:true})
+],"Existing orientation, sizes, valign, wrap, responsive, and flexForChildren options remain. Splitter preserves min/max sizes and resize callbacks, and supports mouse, touch, pen, and keyboard. Responsive horizontal panels stack below 70em; splitters hide in that layout.");
+const treeStatus=text("p","Select a node to explore.");treeStatus.attr={role:"status"};
+const makeTree=()=>({id:"workspace",content:"Workspace",children:[{id:"projects",content:"Projects",children:[{id:"design",content:"Design system"},{id:"website",content:"Website refresh"}]},{id:"archive",content:"Archive",collapsed:true,children:[{id:"last-year",content:"Last year's work"}]},{id:"notes",content:"Notes"}]});
+export const treeShowcase=section("trees","19","Tree views","A calm hierarchy with clear expansion and selection states.",[
+    new TreeViewComponent({data:makeTree(),ariaLabel:"Workspace files",onSelect:item=>{treeStatus.content="Selected: "+item.id;}}),treeStatus,
+    text("h3","Custom row content"),new TreeViewComponent({data:makeTree(),ariaLabel:"Rich file tree",renderItem:item=>group([text("span",item.children?.length ? "▱" : "·"),text("span",String(item.content))],"tree-demo-content")})
+],"The data, collapsed, content, and renderItem options remain. Expansion updates collapsed on the data node. onSelect and ariaLabel are optional additions. Use arrows, Home/End, Enter, or Space; node IDs are data identifiers and do not collide across trees.");
+const overlayCopy=()=>group([text("h2","Workspace settings"),text("p","A little room for secondary tasks, without leaving your current view."),new ButtonComponent({content:"Save settings",type:"button",click:()=>overlay.close()})]);
+let overlay:OverlayComponent;
+let allowClose=false;
+export const overlayShowcase=section("overlays","20","Overlays","Focused panels that slide in from the side or the top.",[
+    group([button("Open side panel",()=>{overlay=OverlayComponent.show({content:overlayCopy(),ariaLabel:"Workspace settings",size:"26rem"});}),button("Open top panel",()=>{overlay=OverlayComponent.show({content:overlayCopy(),direction:"top",size:"20rem",ariaLabel:"Workspace settings"});}),button("Try close guard",()=>{allowClose=false;overlay=OverlayComponent.show({ariaLabel:"Protected panel",onClose:()=>allowClose,content:group([text("h2","A protected panel"),text("p","Closing is blocked until you choose Allow close."),button("Allow close",()=>{allowClose=true;overlay.close();})])});})],"sample-row")
+],"show(), close(), content, direction, size, animation, dismissal flags, and callbacks remain. onClose returning false vetoes dismissal. Native modal dialogs contain keyboard focus, support nested panels, and restore focus on close. ariaLabel and closeButtonLabel provide accessible names.");
+const ribbonStatus=text("p","Choose an action.");ribbonStatus.attr={role:"status"};
+const ribbonAction=(content:string)=>button(content,()=>{ribbonStatus.content=content+" selected.";});
+export const ribbonShowcase=section("ribbons","21","Ribbon menus","Related actions grouped in a flexible, themed toolbar.",[
+    new RibbonMenuComponent([{title:"Project",children:[ribbonAction("New"),ribbonAction("Open"),ribbonAction("Save")]},{title:"Edit",children:[ribbonAction("Undo"),ribbonAction("Redo")]},{title:"View",children:[new ButtonComponent({content:"Details",toggle:true,outlined:true,type:"button"}),new ButtonComponent({content:"Unavailable",enabled:false,type:"button"})]}]),ribbonStatus
+],"The groups constructor and group title/children interface remain unchanged. Groups wrap with available space and use the normal ButtonComponent styles, including toggles and disabled actions.");