jsl-ui 9.28.7 → 10.0.0

package/docs/AutoSuggestComponent.md

@@ -0,0 +1,17 @@
+# AutoSuggestComponent
+
+```ts
+import { AutoSuggestComponent } from "jsl-ui";
+
+const cities = ["Vienna", "London", "Berlin"];
+const city = new AutoSuggestComponent({
+  ariaLabel: "City", minChars: 1,
+  source: (term, suggest) => {
+    suggest(cities.filter(name => name.toLowerCase().includes(term.toLowerCase())));
+  }
+});
+```
+
+- `source` must call `suggest(items)`, including after an asynchronous lookup; returning an array or promise alone does not populate results.
+- Values are text. Custom `renderItem` returns HTML, so escape any untrusted item text.
+- `getRef()` is available only after mounting an enabled, editable control.

package/docs/ButtonComponent.md

@@ -0,0 +1,14 @@
+# ButtonComponent
+
+```ts
+import { ButtonComponent } from "jsl-ui";
+
+const bookmark = new ButtonComponent({
+  content: "Bookmark", type: "button", toggle: true,
+  onToggle: pressed => { /* persist selection */ }
+});
+```
+
+- Set `type: "button"` for actions inside forms; omitting it retains native submit behavior.
+- `pressed` is the initial state. Afterwards, use `bookmark.pressed`; assigning it does not raise callbacks.
+- Icon strings are literal text, not HTML or icon-library class names. Supply a VNode/component for markup; name icon-only buttons with `ariaLabel` or hidden `content`.

package/docs/CheckBoxComponent.md

@@ -0,0 +1,12 @@
+# CheckBoxComponent
+
+```ts
+import { CheckBoxComponent } from "jsl-ui";
+
+const archived = new CheckBoxComponent({
+  label: "Include archived projects", value: false
+});
+```
+
+- `indeterminate` is a separate visual state, not a third value; `getValue()` remains boolean.
+- `setValue()` updates the binding without raising change callbacks.

package/docs/DateComponent.md

@@ -0,0 +1,12 @@
+# DateComponent
+
+```ts
+import { DateComponent } from "jsl-ui";
+
+const due = new DateComponent({
+  value: new Date(2026, 9, 23), ariaLabel: "Due date"
+});
+```
+
+- Values and bindings use `Date` objects; display and parsing follow the culture helper. Supply both `format` and `parse` when overriding that convention.
+- `getValue()` returns text; use `isValid()` and `getValueAsDate()` when reading edited dates. `setValue()` does not raise change callbacks.

package/docs/DateRangeComponent.md

@@ -0,0 +1,13 @@
+# DateRangeComponent
+
+```ts
+import { DateRangeComponent } from "jsl-ui";
+
+const range = new DateRangeComponent({
+  min: new Date(2026, 9, 1), max: new Date(2026, 9, 31), increment: "days",
+  minValue: new Date(2026, 9, 5), maxValue: new Date(2026, 9, 20)
+});
+```
+
+- Only `increment: "days"` is implemented, despite the broader type. Dates are normalized to local calendar days; bounds must be valid and ascending.
+- `min` / `max` are bounds; `minValue` / `maxValue` are the initial selection. Read the selection through `getMin()` / `getMax()` or `onChange`.

package/docs/DateTimeComponent.md

@@ -0,0 +1,13 @@
+# DateTimeComponent
+
+```ts
+import { DateTimeComponent } from "jsl-ui";
+
+const appointment = new DateTimeComponent({
+  value: new Date(2026, 9, 23, 9, 30),
+  dateAriaLabel: "Appointment date", timeAriaLabel: "Appointment time"
+});
+```
+
+- Bind the composite control to one `Date`; it combines the date and time inputs. `getValueAsDate()` returns `null` for invalid input; `getValue()` returns text.
+- `setValue()` updates both inputs without raising change callbacks. The control edits local date/time, without timezone conversion.

package/docs/DialogComponent.md

@@ -0,0 +1,15 @@
+# DialogComponent
+
+```ts
+import { DialogComponent } from "jsl-ui";
+
+const dialog = DialogComponent.show({
+  header: "Confirm changes", content: "Save this version?",
+  footer: { tag: "div", children: [
+    DialogComponent.Cancel(), DialogComponent.Ok(() => { /* save changes */ })
+  ] }
+});
+```
+
+- `show()` mounts and cleans up its own host. To close programmatically, use `dialog.getRef().close()`.
+- Footer helper buttons close the dialog unless their callback returns `false` (also after awaiting a promise). `onClose` can veto any close by returning `false`.

package/docs/ExpanderComponent.md

@@ -0,0 +1,13 @@
+# ExpanderComponent
+
+```ts
+import { ExpanderComponent, InputComponent } from "jsl-ui";
+
+const advanced = new ExpanderComponent({
+  header: "Advanced options", expanded: false,
+  body: new InputComponent({ ariaLabel: "Reference", placeholder: "Reference" })
+});
+```
+
+- Collapsing hides the body but keeps it mounted.
+- Return `false` from `onToggle` to veto a user toggle. `setExpanded()` changes state without calling `onToggle`.

package/docs/FormComponent.md

@@ -0,0 +1,15 @@
+# FormComponent
+
+```ts
+import { FormComponent, FormFieldComponent, InputComponent } from "jsl-ui";
+
+const form = new FormComponent([
+  new FormFieldComponent({
+    label: "Project", required: true,
+    control: new InputComponent({ id: "project-name" })
+  })
+]);
+```
+
+- `form.validate()` calls validators on direct children only. Keep fields as direct children if relying on this method.
+- This is a native form; it does not intercept submission. Validate in your submit/action handler; use `type: "button"` for buttons that should not submit.

package/docs/FormFieldComponent.md

@@ -0,0 +1,15 @@
+# FormFieldComponent
+
+```ts
+import { FormFieldComponent, InputComponent } from "jsl-ui";
+
+const field = new FormFieldComponent({
+  label: "Project", required: true,
+  control: new InputComponent({ id: "project-name", value: "Website" })
+});
+```
+
+- Put editing, binding, and formatting on the child control. The field supplies its label, layout, and validation feedback.
+- Call `validate()` when submitting; `required` does not submit or validate the surrounding form automatically.
+- `getValue()` / `setValue()` delegate to supplied controls. Match the child's value contract; the legacy `type` factory may use strings instead.
+- For custom markup with several inputs, set `controlId` to identify the label target.

package/docs/GridComponent.md

@@ -0,0 +1,19 @@
+# GridComponent
+
+```ts
+import { GridComponent, NumericFormatter } from "jsl-ui";
+
+const grid = new GridComponent(
+  [{ id: 1, amount: 1250.5 }],
+  [{ id: "amount", name: "Amount", width: 140,
+     formatter: NumericFormatter, headerCssClass: "right" }],
+  { primaryKey: "id" }, "300px"
+);
+grid.initEvents(g => { /* subscribe to grid events here */ });
+```
+
+- Use unique, stable primary keys. Mount before awaiting `getRef()`; register initialization callbacks with `initEvents()`.
+- Keep component instances stable across parent renders so unrelated UI updates do not recreate the grid.
+- Preserve `content-box` on cells and headers. Selection/formatter classes must not change padding or border widths.
+- NumericFormatter aligns cells; header alignment is explicit via `headerCssClass: "right"` or `"center"`.
+- Register dependent calculations with `addFormula()`, then call `triggerAllFormulas()` for initial values. See [the showcase](../examples/showcase/grids.ts) for formulas, totals, frozen columns, and row ordering.

package/docs/InputComponent.md

@@ -0,0 +1,15 @@
+# InputComponent
+
+```ts
+import { InputComponent } from "jsl-ui";
+
+const model = { name: "Website" };
+const input = new InputComponent({
+  bindTo: model, property: "name", bindMode: "both",
+  bindOnInput: true, ariaLabel: "Project name"
+});
+```
+
+- Binding defaults to `"toModel"`. Use `"both"` to also read external model changes on render; `bindOnInput` writes while typing rather than waiting for change.
+- `setValue()` updates the binding without raising change callbacks.
+- Use [FormFieldComponent](FormFieldComponent.md) for a visible label. Keep the default control styling unless the host deliberately supplies its own via `unstyled`.

package/docs/IntervalComponent.md

@@ -0,0 +1,13 @@
+# IntervalComponent
+
+```ts
+import { IntervalComponent } from "jsl-ui";
+
+const state = { ticks: 0 };
+const timer = new IntervalComponent(() => { state.ticks++; }, {
+  interval: 30000, stopOnError: true
+});
+```
+
+- Mount the component to start it; the callback runs immediately, then repeats after the interval in milliseconds. Async callbacks settle before the next delay begins.
+- The owning view refreshes after callbacks unless `noRefresh` is set. Unmounting clears the pending timeout; cancellation of in-flight asynchronous work belongs to your callback.

package/docs/LoadingComponent.md

@@ -0,0 +1,12 @@
+# LoadingComponent
+
+```ts
+import { LoadingComponent } from "jsl-ui";
+
+const loading = new LoadingComponent({
+  sizeInRem: 1.25, label: "Loading report", showLabel: true
+});
+```
+
+- Specify size for compact layouts; the legacy default is `6rem`.
+- The label remains accessible when visually hidden. The indicator does not disable controls or manage the surrounding content's `aria-busy` state.

package/docs/NavigationComponent.md

@@ -0,0 +1,17 @@
+# NavigationComponent
+
+```ts
+import { NavigationComponent } from "jsl-ui";
+
+const navigation = new NavigationComponent({
+  title: "Workspace", position: "default",
+  data: [
+    { content: "Projects", link: "#projects" },
+    { content: "Settings", children: [{ content: "Profile", link: "#profile" }] }
+  ]
+});
+```
+
+- Position defaults to `"fixed"`; use `"default"` or `"static"` to participate in the page layout.
+- Items with `link` use native anchors; callback-only items use buttons. Children provide submenus.
+- Active links follow the current location. For a custom router, update `activeLink` in the options and refresh the view.

package/docs/Notification.md

@@ -0,0 +1,14 @@
+# Notification
+
+```ts
+import { Notification } from "jsl-ui";
+
+const id = Notification.show({
+  title: "Saved", content: "Your changes have been saved.",
+  variant: "success", timeOut: 4000
+});
+```
+
+- `show()` owns the floating stack. Use `clearNotification(id)` for targeted dismissal or `clearAll()` for the whole stack.
+- `timeOut` is milliseconds; omitted or zero means persistent. Timed notifications show a countdown that pauses on hover/focus.
+- Clicking the body dismisses by default. Set `closeOnClick: false` when the content contains actions.

package/docs/NotificationComponent.md

@@ -0,0 +1,13 @@
+# NotificationComponent
+
+```ts
+import { NotificationComponent } from "jsl-ui";
+
+const notice = new NotificationComponent({
+  title: "Review needed", content: "Check the project settings.",
+  variant: "warning", closeOnClick: false
+});
+```
+
+- Mount this inline like other components. `dismiss()` hides it; the parent owns removal.
+- Automatic dismissal and countdowns require the host provided by [Notification.show()](Notification.md); `timeOut` alone does not start a timer on an inline component.

package/docs/NumberComponent.md

@@ -0,0 +1,12 @@
+# NumberComponent
+
+```ts
+import { NumberComponent } from "jsl-ui";
+
+const amount = new NumberComponent({
+  value: 1250.5, format: "#,0.00", ariaLabel: "Amount"
+});
+```
+
+- Format masks use invariant comma/dot syntax; displayed separators and parsing follow the culture helper.
+- `getValue()` returns formatted text; use `getValueAsNumber()` for calculations. `setValue()` takes a number and does not raise change callbacks.

package/docs/OverlayComponent.md

@@ -0,0 +1,12 @@
+# OverlayComponent
+
+```ts
+import { OverlayComponent } from "jsl-ui";
+
+const panel = OverlayComponent.show({
+  ariaLabel: "Settings", content: "Application settings", size: "26rem"
+});
+```
+
+- `show()` owns mounting and cleanup; `panel.close()` closes it. The overlay is modal and defaults to a left-side panel.
+- Escape and backdrop clicks close by default. Return `false` from `onClose` to veto closing.

package/docs/ProgressComponent.md

@@ -0,0 +1,12 @@
+# ProgressComponent
+
+```ts
+import { ProgressComponent } from "jsl-ui";
+
+const upload = new ProgressComponent(45, {
+  ariaLabel: "Upload progress", showPercent: true
+});
+```
+
+- Progress uses `0..100`, not `0..1`.
+- `setProgress()` changes the value without refreshing. When updating outside renderer-managed events, refresh the owning `jsl-render` view yourself.

package/docs/README.md

@@ -0,0 +1,24 @@
+# jsl-ui: agent guide
+
+- Import from the package root, e.g. `import { GridComponent, NumericFormatter } from "jsl-ui"`. Mount components with `jsl-render`; the static `show()` helpers mount themselves.
+- Use a browser bundler that handles CSS/SCSS imports. Components import their own styles.
+- Theme through `--jsl-color-*` variables on the application or a container; avoid overriding internal markup.
+- [Showcase sources](../examples/showcase/) are included as usage references.
+- Consult the shipped `lib/**/*.d.ts` files for options; these guides cover usage decisions rather than duplicate interfaces.
+
+Guides for the public components exported by `jsl-ui`:
+
+- [ButtonComponent](ButtonComponent.md)
+- [InputComponent](InputComponent.md), [NumberComponent](NumberComponent.md), [AutoSuggestComponent](AutoSuggestComponent.md)
+- [CheckBoxComponent](CheckBoxComponent.md), [SelectComponent](SelectComponent.md)
+- [DateComponent](DateComponent.md), [TimeComponent](TimeComponent.md), [DateTimeComponent](DateTimeComponent.md), [DateRangeComponent](DateRangeComponent.md)
+- [FormFieldComponent](FormFieldComponent.md)
+- [FormComponent](FormComponent.md)
+- [TabsComponent](TabsComponent.md), [ExpanderComponent](ExpanderComponent.md)
+- [StackPanelComponent](StackPanelComponent.md), [SplitterComponent](SplitterComponent.md)
+- [TreeViewComponent](TreeViewComponent.md), [NavigationComponent](NavigationComponent.md), [RibbonMenuComponent](RibbonMenuComponent.md)
+- [DialogComponent](DialogComponent.md), [OverlayComponent](OverlayComponent.md)
+- [Notification](Notification.md), [NotificationComponent](NotificationComponent.md)
+- [ProgressComponent](ProgressComponent.md), [LoadingComponent](LoadingComponent.md)
+- [GridComponent](GridComponent.md)
+- [IntervalComponent](IntervalComponent.md)

package/docs/RibbonMenuComponent.md

@@ -0,0 +1,14 @@
+# RibbonMenuComponent
+
+```ts
+import { ButtonComponent, RibbonMenuComponent } from "jsl-ui";
+
+const ribbon = new RibbonMenuComponent([
+  { title: "File", children: [
+    new ButtonComponent({ content: "Open", type: "button" }),
+    new ButtonComponent({ content: "Save", type: "button" })
+  ] }
+]);
+```
+
+- The ribbon groups controls; commands, toggle state, and enabled state belong to those child controls. Use `type: "button"` for commands inside forms.

package/docs/SelectComponent.md

@@ -0,0 +1,15 @@
+# SelectComponent
+
+```ts
+import { SelectComponent } from "jsl-ui";
+
+const teams = new SelectComponent({
+  ariaLabel: "Teams", multiple: true,
+  data: [{ value: "design", text: "Design" }, { value: "engineering", text: "Engineering" }],
+  value: ["design"]
+});
+```
+
+- `value` / `getValue()` use keys from `keyColumn` (default `"value"`); `getSelected()` returns the matching data objects. Multiple selection uses arrays; single selection uses a scalar.
+- Omit `multiple` and use `value: "design"` for single selection with the same data.
+- `setValue()` takes keys and updates the binding without raising change callbacks. The component owns its dropdown; do not create `SelectDDAreaComponent` separately.

package/docs/SplitterComponent.md

@@ -0,0 +1,14 @@
+# SplitterComponent
+
+```ts
+import { SplitterComponent, StackPanelComponent } from "jsl-ui";
+
+const layout = new StackPanelComponent([
+  { tag: "div", content: "Sidebar" },
+  new SplitterComponent({ minSizesInPX: [120, 180], ariaLabel: "Resize sidebar" }),
+  { tag: "div", content: "Main content" }
+], { sizes: ["40%", undefined, "*"], style: "height:20rem" });
+```
+
+- Place directly between two panels in a `StackPanelComponent`; orientation comes from the stack. Leave its entry in `sizes` undefined.
+- Min/max arrays refer to the preceding and following panel. `onResizeDone` receives the preceding panel's size, including height for a vertical stack.

package/docs/StackPanelComponent.md

@@ -0,0 +1,13 @@
+# StackPanelComponent
+
+```ts
+import { StackPanelComponent } from "jsl-ui";
+
+const layout = new StackPanelComponent([
+  { tag: "div", content: "Sidebar" },
+  { tag: "div", content: "Main content" }
+], { sizes: ["12rem", "*"] });
+```
+
+- Children get layout wrappers; `"*"` fills remaining space. Size indices match the children array, including any [SplitterComponent](SplitterComponent.md).
+- `responsive: true` stacks horizontal panels and hides splitters on narrow screens. Give vertical layouts a definite height when distributing available height.

package/docs/TabsComponent.md

@@ -0,0 +1,16 @@
+# TabsComponent
+
+```ts
+import { TabsComponent } from "jsl-ui";
+
+const tabs = new TabsComponent({
+  preserveContent: true,
+  tabs: [
+    { header: "Overview", content: "Project overview" },
+    { header: "Details", onCreate: () => "Project details" }
+  ]
+});
+```
+
+- `onCreate` lazily supplies content on first activation. `preserveContent: true` keeps visited panels mounted; by default inactive panels are removed.
+- `onSelect` and `onClosing` can return `false` to veto user actions. `SetSelectedTab(index)` changes selection without calling `onSelect`.

package/docs/TimeComponent.md

@@ -0,0 +1,13 @@
+# TimeComponent
+
+```ts
+import { TimeComponent } from "jsl-ui";
+
+const time = new TimeComponent({
+  value: new Date(2026, 9, 23, 9, 30), ariaLabel: "Start time"
+});
+const start = time.getValueAsDate(new Date(2026, 9, 23));
+```
+
+- `getValueAsDate(datePart)` combines the edited time with the supplied calendar date; invalid input returns `null`. `getValue()` returns text.
+- Use `inputMode: "HourMinuteSecond"` to include seconds. `setValue()` takes a `Date` without raising change callbacks.

package/docs/TreeViewComponent.md

@@ -0,0 +1,16 @@
+# TreeViewComponent
+
+```ts
+import { TreeViewComponent } from "jsl-ui";
+
+const tree = new TreeViewComponent({
+  ariaLabel: "Project files",
+  data: { id: "project", content: "Project", children: [
+    { id: "notes", content: "Notes" },
+    { id: "assets", content: "Assets" }
+  ] }
+});
+```
+
+- `data` is one root node, not an array; node IDs must be unique within the tree.
+- Branch activation selects the node and changes its `collapsed` property in the supplied data. Keep that data stable to preserve expansion state.

package/examples/showcase/checks-and-expanders.ts

@@ -0,0 +1,163 @@
+import { IJSLComponent, IJSLVNode } from "jsl-render";
+import { CheckBoxComponent } from "../../components/checkbox/CheckBoxComponent";
+import { ExpanderComponent } from "../../components/expander/ExpanderComponent";
+import { ButtonComponent } from "../../components/button/ButtonComponent";
+
+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 copy = (title: string, content: string) => group([text("h4", title), text("p", content)], "expander-example-copy");
+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 checks-expander-preview")
+        ], "hero"),
+        group(cards, "sample-grid checks-expander-grid"),
+        { tag: "details", attr: { class: "usage" }, children: [text("summary", title + " usage & compatibility"), ...usage] }
+    ] };
+}
+
+const basicStatus = status("Email updates are off.");
+const partialStatus = status("1 of 3 channels selected.");
+const channels = ["Product news", "Release notes", "Community events"].map((label, index) => new CheckBoxComponent({
+    id: "checkbox-channel-" + index, label, value: index === 0,
+    onChange: () => syncChannels()
+}));
+const allChannels = new CheckBoxComponent({
+    id: "checkbox-all", label: "All updates", indeterminate: true,
+    onChange: checked => { channels.forEach(channel => channel.setValue(checked)); syncChannels(); }
+});
+function syncChannels() {
+    const count = channels.filter(channel => channel.getValue()).length;
+    allChannels.setValue(count === channels.length);
+    allChannels.indeterminate = count > 0 && count < channels.length;
+    partialStatus.content = count + " of " + channels.length + " channels selected.";
+}
+const model = { digest: 1 };
+const bindingStatus = status("Model value: 1");
+const boundCheck = new CheckBoxComponent({
+    id: "checkbox-bound", label: "Send a weekly digest", bindTo: model, property: "digest", bindMode: "both",
+    converter: { toUI: value => value === 1, toData: checked => checked ? 1 : 0 },
+    onChange: () => { bindingStatus.content = "Model value: " + model.digest; }
+});
+
+export const checkboxShowcase = section("checkboxes", "09", "Checkboxes",
+    "Small choices, clearly marked. Comfortable labels and a visible place for focus.",
+    group([
+        new CheckBoxComponent({ label: "Keep me informed", value: true }),
+        new CheckBoxComponent({ label: "Share usage insights" })
+    ], "checkbox-stack"), [
+        card("checkbox-basic", "01", "One clear choice", "Click the box or its label. Tab focuses the input; Space changes its state.", [
+            new CheckBoxComponent({ id: "checkbox-basic-input", label: "Email me product updates", onChange: checked => {
+                basicStatus.content = checked ? "Email updates are on." : "Email updates are off.";
+            } }), basicStatus,
+            text("pre", '{ label: "Email me product updates", onChange: checked => { ... } }', "sample-code")
+        ]),
+        card("checkbox-states", "02", "A little more context", "Supporting text explains a choice. Disabled controls keep their labels and current state.", [
+            group([
+                new CheckBoxComponent({ id: "checkbox-description", label: "Remember this workspace", description: "Open this workspace automatically the next time you sign in.", value: true }),
+                new CheckBoxComponent({ id: "checkbox-disabled", label: "Managed by your administrator", enabled: false }),
+                new CheckBoxComponent({ id: "checkbox-disabled-checked", label: "Security notifications", value: true, enabled: false })
+            ], "checkbox-stack")
+        ]),
+        card("checkbox-partial", "03", "Some, all, or none", "A mixed parent summarizes its children. Activating it selects or clears the whole group.", [
+            group([allChannels, group(channels, "checkbox-child-list")], "checkbox-stack"), partialStatus,
+            text("pre", "checkbox.indeterminate = true;\ncheckbox.setValue(true); // Silent checked update", "sample-code")
+        ]),
+        card("checkbox-binding", "04", "Connected to your model", "A converter maps checked state to a numeric value. Two-way binding keeps the display in sync.", [
+            boundCheck, bindingStatus,
+            group([action("Toggle from the model", () => {
+                model.digest = model.digest === 1 ? 0 : 1;
+                bindingStatus.content = "Model value: " + model.digest;
+            })], "sample-row")
+        ])
+    ], [
+        text("pre", 'new CheckBoxComponent({\n  label: "Send a weekly digest",\n  value: true,\n  bindTo: model, property: "digest", bindMode: "both",\n  onChange: checked => console.log(checked)\n});', "sample-code"),
+        text("p", "Existing value, label, enabled, class, style, id, binding, converter, onChange, getValue(), and setValue() APIs are preserved. class still applies to the input and style to its wrapper. setValue() works before mounting, updates writable bindings, and does not raise onChange."),
+        text("p", "The optional description is associated with the input as supporting text. Use ariaLabel when the visible label is empty. indeterminate sets an initial mixed state; the indeterminate property can update it later. The next user activation clears mixed state and raises the usual boolean change event.")
+    ]);
+
+const basicExpanderStatus = status("Details are expanded.");
+const preservedStatus = status("Collapse and reopen to keep your draft.");
+let allowCollapse = false;
+const guardedStatus = status("Closing is currently blocked.");
+const headerStatus = status("The header action has not been used.");
+const nested = new ExpanderComponent({
+    header: "Workspace settings",
+    body: group([
+        new ExpanderComponent({ header: "Notifications", expanded: false, body: group([
+            new CheckBoxComponent({ label: "Email notifications", value: true }),
+            new CheckBoxComponent({ label: "Desktop notifications" })
+        ], "checkbox-stack") }),
+        new ExpanderComponent({ header: "Privacy", expanded: false, body: copy("Your preferences", "Choose what you share and how your workspace appears to others.") })
+    ], "expander-stack")
+});
+const customIcons = new ExpanderComponent({
+    header: "A different indicator", body: copy("Make it your own", "Supply custom expandedIcon and collapsedIcon nodes to match your application."),
+    expanded: false, expandedIcon: text("span", "−", "expander-custom-icon"), collapsedIcon: text("span", "+", "expander-custom-icon")
+});
+
+export const expanderShowcase = section("expanders", "10", "Expanders",
+    "Keep the overview clear. Open the details when you need them.",
+    new ExpanderComponent({ header: "Project details", body: text("p", "A little more context, close at hand.", "expander-preview-copy") }), [
+        card("expander-basic", "01", "Details on demand", "The whole header toggles the section. Its native button also responds to Enter and Space.", [
+            new ExpanderComponent({
+                header: "About this project", body: copy("A place to get started", "Keep the essentials visible and tuck supporting information into a section that is easy to open."),
+                onToggle: expanded => { basicExpanderStatus.content = expanded ? "Details are expanded." : "Details are collapsed."; }
+            }), basicExpanderStatus
+        ]),
+        card("expander-preserved", "02", "Keep unfinished work", "Collapsing hides the body while keeping its inputs and components mounted.", [
+            new ExpanderComponent({
+                header: "Project draft",
+                body: group([
+                    { tag: "label", content: "Project name", attr: { for: "expander-draft" } },
+                    { tag: "input", attr: { id: "expander-draft", class: "tabs-draft-input", placeholder: "Type a draft, then collapse this section" } },
+                    new CheckBoxComponent({ id: "expander-draft-checkbox", label: "Share with my team" })
+                ], "expander-example-copy"),
+                onToggle: expanded => { preservedStatus.content = expanded ? "Your draft is still here." : "Draft hidden and preserved."; }
+            }), preservedStatus
+        ]),
+        card("expander-header", "03", "Room for a header action", "Use isToggleOnHeader: false to toggle only with the indicator and keep header actions independent.", [
+            new ExpanderComponent({
+                isToggleOnHeader: false,
+                header: group([text("span", "Team members"), action("Invite", () => { headerStatus.content = "Invite action used. Expansion is unchanged."; })], "expander-rich-header"),
+                body: copy("Work together", "Invite people to the workspace and keep everyone in the same place."),
+                ariaLabel: "Team members"
+            }), headerStatus
+        ]),
+        card("expander-guarded", "04", "Keep important details open", "Return false from onToggle to veto a change. Allow closing with the checkbox below.", [
+            new ExpanderComponent({
+                header: "Unsaved changes",
+                body: copy("A draft needs your attention", "This section stays open until you allow it to close."),
+                onToggle: expanding => {
+                    if (!expanding && !allowCollapse) { guardedStatus.content = "Still open. Allow closing to continue."; return false; }
+                    guardedStatus.content = expanding ? "Section opened." : "Section closed.";
+                }
+            }),
+            group([new CheckBoxComponent({ id: "expander-allow-close", label: "Allow closing", onChange: value => { allowCollapse = value; } })], "sample-row"),
+            guardedStatus
+        ]),
+        card("expander-nested", "05", "One level at a time", "Nested sections stay independent. Opening Notifications or Privacy keeps the parent in place.", [nested]),
+        card("expander-options", "06", "A familiar shape, your details", "Custom indicators and disabled toggles use the same surface and theme.", [
+            group([
+                customIcons,
+                new ExpanderComponent({ header: "Unavailable section", body: "This section is not available yet.", expanded: false, enabled: false })
+            ], "expander-stack")
+        ])
+    ], [
+        text("pre", 'new ExpanderComponent({\n  header: "Project details", body: content, expanded: true,\n  onToggle: expanding => { /* Return false to veto. */ }\n});\n\nexpander.setExpanded(false); // Silent update\nexpander.toggle();           // Consults onToggle', "sample-code"),
+        text("p", "Both the options constructor and new ExpanderComponent(header, body, expanded) remain supported. expanded still defaults to true. Existing icons, iconSize, isToggleOnHeader, class, style, getIcon(), onToggle, and State.expanded remain available. Optional id, ariaLabel, and enabled add labeling and disabled behavior."),
+        text("p", "isExpanded() reads the current state. setExpanded() changes it silently; toggle() follows the same callback and veto rules as user activation. State and panel IDs survive parent renders that create a new ExpanderComponent instance. Collapsing preserves the body and returns focus to the toggle if focus was inside it."),
+        text("p", "Custom headers can contain independent buttons, links, and form inputs. Those controls do not toggle the section. The body is a named region connected to its button. Reduced-motion preferences disable the short reveal animation.")
+    ]);