@imfusion/web-ui 0.10.0 → 0.10.1-dev.11.g9f5bc06e

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # Changelog
 
+## [Unreleased]
+
+### Breaking
+
+- **Breaking:** `AppShell.Main`, the AppShell aside drawer, and `Drawer.Content` scroll in a `ScrollArea` and pad their
+  content inside it ([WEBSDK-247](https://imfusion.atlassian.net/browse/WEBSDK-247)). — Nikolaus Brunner <brunner@imfusion.com>
+  - `AppShell.Main` stays the scrolling element and pads with `--imf-ui-appshell-padding`; a `padding` set on it adds to
+    that.
+  - `Drawer.Content` pads with `--imf-ui-drawer-content-padding`; a `padding`, `gap`, or grid set on it applies outside the
+    padded layer and does not reach the children.
+  - The aside drawer pads its content inside the scroll area; a `padding` on `AppShell.Aside` in drawer mode adds to it.
+
+### Added
+
+- `ScrollArea` is a scrolling region with a slim primary-colored thumb that floats over the content and shows while the
+  area is hovered or scrolled, and a fade at each edge with more content behind it. `ScrollArea.Auto` wraps children with
+  the scrollbars for `orientation` (`vertical`, `horizontal`, `both`, or `none`); the parts compose by hand for anything else
+  ([WEBSDK-247](https://imfusion.atlassian.net/browse/WEBSDK-247)) — Nikolaus Brunner <brunner@imfusion.com>
+- `Dialog` is a modal window over a dimmed page, adapted from Base UI with all its parts. `Dialog.Header` takes a
+  `variant` (`main`, `support`, `minor`, or `primary` with light text); `Dialog.Title` renders as `Typo.H2` and
+  `Dialog.Description` as `Typo.P`. `Dialog.Body` scrolls in a `ScrollArea` while header and footer stay in view.
+  `Dialog.Popup` comes in `sm`, `md`, `lg`, and `full`, and stops at 40rem high (`--imf-ui-dialog-max-height`) except in
+  `full`. `Dialog.Status` adds a tinted status column like `Card.Status`, on top of the width the size sets.
+  `Dialog.Simple` builds the whole dialog from props, and `Dialog.Inline` opens it from a term inside running text
+  ([WEBSDK-247](https://imfusion.atlassian.net/browse/WEBSDK-247)) — Nikolaus Brunner <brunner@imfusion.com>
+
+### Changed
+
+- Agent skills — Nikolaus Brunner <brunner@imfusion.com>
+  - `imf-web-ui-conventions` has query factories own a numeric `staleTime` chosen by how fast other people change the data.
+    Loaders call `queryClient.query(options)` without an override, and `"static"` no longer appears in factories or
+    `defaultOptions`, where it blocked invalidation refetches.
+  - `imf-web-ui-conventions` puts a route's own views, forms, hooks, and tests in a `-<file-name>/` folder beside the route
+    file, and reserves `partials/` for parts that more than one route uses.
+- Components ([WEBSDK-247](https://imfusion.atlassian.net/browse/WEBSDK-247)) — Nikolaus Brunner <brunner@imfusion.com>
+  - The AppShell navbar drawer, `Code`, and `ImageDisplayOptions` scroll in a `ScrollArea`, with its overlay thumb and edge
+    fades.
+
+---
+
 ## `0.10.0` &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2026.10.15
 
 ### Highlights
@@ -234,6 +274,37 @@ AppShell sections draw no dividers. Delete overrides of the border properties, w
 - --imf-ui-appshell-border-width: var(--imf-ui-border-size-2);
 ```
 
+Navbar sections pad themselves with `--imf-ui-appshell-navbar-padding`, and that rule outranks a single class. Delete your
+own section padding, and set the variable when the gutter needs to change:
+
+```diff
+- .navSection { padding: 0 var(--imf-ui-appshell-padding); }
++ .root { --imf-ui-appshell-navbar-padding: var(--imf-ui-size-5); }
+```
+
+Nav links widen past the gutter only as `AppShell.NavItem`. Replace hand-built navbar links, and pass a router link through
+`render`:
+
+```diff
+- <MyNavLink to="/products" icon={Box} label="Products" />
++ <AppShell.NavItem render={<Link to="/products" />} icon={<Icon glyph={Box} />}>Products</AppShell.NavItem>
+```
+
+Above `lg` the aside docks whether or not `open` is set. Render no aside when there is nothing to show, not an empty one:
+
+```diff
+- <AppShell.Aside>{selected ? <Details /> : <div />}</AppShell.Aside>
++ {selected ? <AppShell.Aside><Details /></AppShell.Aside> : null}
+```
+
+The navbar's first row and Main's offset read the header height while an `AppShell.Header` is rendered, even when CSS hides
+it. Render the header conditionally instead of hiding it or setting the height to `0`:
+
+```diff
+- <AppShell.Header className={styles.hiddenOnDesktop}>…</AppShell.Header>
++ {isDesktop ? null : <AppShell.Header>…</AppShell.Header>}
+```
+
 ### Breaking
 
 - **Breaking:** The library supports Safari 17.5, Chrome 123, and Firefox 120 or newer. — Nikolaus Brunner <brunner@imfusion.com>
@@ -241,6 +312,11 @@ AppShell sections draw no dividers. Delete overrides of the border properties, w
   - The JavaScript build targets the same versions.
 - **Breaking:** AppShell sections draw no dividers, and the `--imf-ui-appshell-border-color`, `--imf-ui-appshell-border-width`, and `--imf-ui-appshell-border-style` properties are removed. ([WEBSDK-243](https://imfusion.atlassian.net/browse/WEBSDK-243)) — Nikolaus Brunner <brunner@imfusion.com>
 - **Breaking:** `AppShell.Main` is the scroll container and the document does not scroll; window scroll listeners, scroll restoration, and `scrollTo` target `AppShell.Main`. ([WEBSDK-243](https://imfusion.atlassian.net/browse/WEBSDK-243)) — Nikolaus Brunner <brunner@imfusion.com>
+- **Breaking:** AppShell owns its navbar and aside layout. ([WEBSDK-243](https://imfusion.atlassian.net/browse/WEBSDK-243)) — Nikolaus Brunner <brunner@imfusion.com>
+  - Navbar sections pad themselves with `--imf-ui-appshell-navbar-padding` through a rule that outranks a single class.
+  - Only `AppShell.NavItem` widens past the navbar gutter.
+  - Above `lg` the aside docks whether or not `open` is set.
+  - The navbar's first row and Main's offset read the header height whenever an `AppShell.Header` is rendered.
 
 ### Added
 

package/dist/code-NTcddiYk.js

@@ -0,0 +1,139 @@
+import { r as e } from "./resolve-state-props-DQf9WiGv.js";
+import { Xo as t, ja as n, pM as r } from "./icons-BsK_o-Cb.js";
+import { t as i } from "./meta-V_KyLeGn.js";
+import { a, i as o, n as s, o as c, s as l } from "./scroll-area-z9Lf9uIk.js";
+import { cx as u } from "class-variance-authority";
+import { Fragment as d, jsx as f, jsxs as p } from "react/jsx-runtime";
+import { useCallback as m, useEffect as h, useRef as g, useState as _ } from "react";
+import { mergeProps as v } from "@base-ui/react/merge-props";
+import { useRender as y } from "@base-ui/react/use-render";
+//#region src/hooks/use-clipboard.ts
+function b({ timeout: e = 1500 } = {}) {
+	let [t, n] = _(!1), r = g(void 0);
+	return h(() => () => clearTimeout(r.current), []), {
+		copied: t,
+		copy: m((t) => {
+			navigator.clipboard.writeText(t).then(() => {
+				n(!0), clearTimeout(r.current), r.current = setTimeout(() => n(!1), e);
+			});
+		}, [e])
+	};
+}
+var x = {
+	block: "imf-ui-code-module-block",
+	copy: "imf-ui-code-module-copy",
+	inline: "imf-ui-code-module-inline",
+	inlineCopy: "imf-ui-code-module-inlineCopy",
+	inlineLink: "imf-ui-code-module-inlineLink",
+	language: "imf-ui-code-module-language",
+	pre: "imf-ui-code-module-pre",
+	separator: "imf-ui-code-module-separator"
+}, S = /* @__PURE__ */ e({
+	Block: () => T,
+	Inline: () => C,
+	InlineLink: () => w
+});
+function C({ copyable: e = !1, children: i, render: a, ...o }) {
+	let { copied: s, copy: c } = b(), l = g(null), u = s ? n : t;
+	return y({
+		defaultTagName: "code",
+		render: a,
+		props: {
+			...v(o, {
+				className: x.inline,
+				children: /* @__PURE__ */ p(d, { children: [
+					/* @__PURE__ */ f("span", {
+						ref: l,
+						children: i
+					}),
+					e && /* @__PURE__ */ f("span", { className: x.separator }),
+					e && /* @__PURE__ */ f("button", {
+						type: "button",
+						className: x.inlineCopy,
+						"data-copied": s || void 0,
+						"aria-label": s ? "Copied" : "Copy",
+						onClick: () => c(l.current?.textContent ?? ""),
+						children: /* @__PURE__ */ f(r, {
+							glyph: u,
+							size: 12,
+							strokeWidth: 2,
+							"aria-hidden": !0
+						})
+					})
+				] })
+			}),
+			"data-imf-ui-component": "Code.Inline"
+		}
+	});
+}
+C.displayName = "Code.Inline";
+function w({ kind: e = "external", ...t }) {
+	let n = e === "external" ? {
+		target: "_blank",
+		rel: "noreferrer"
+	} : {};
+	return y({
+		defaultTagName: "a",
+		render: t.render,
+		props: {
+			...v(n, t, {
+				className: u(x.inline, x.inlineLink, t.className),
+				children: t.children
+			}),
+			"data-imf-ui-component": "Code.InlineLink",
+			"data-kind": e
+		}
+	});
+}
+w.displayName = "Code.InlineLink";
+function T({ className: e, language: i, hideCopy: d = !1, children: m, ...h }) {
+	let { copied: _, copy: v } = b(), y = g(null), S = _ ? n : t;
+	return /* @__PURE__ */ p("div", {
+		"data-imf-ui-component": "Code.Block",
+		className: u(x.block, e),
+		children: [
+			i != null && /* @__PURE__ */ f("span", {
+				className: x.language,
+				children: i
+			}),
+			!d && /* @__PURE__ */ f("button", {
+				type: "button",
+				className: x.copy,
+				"data-copied": _ || void 0,
+				"aria-label": _ ? "Copied" : "Copy",
+				onClick: () => v(y.current?.textContent ?? ""),
+				children: /* @__PURE__ */ f(r, {
+					glyph: S,
+					size: 12,
+					strokeWidth: 2,
+					"aria-hidden": !0
+				})
+			}),
+			/* @__PURE__ */ p(o, { children: [/* @__PURE__ */ f(l, { children: /* @__PURE__ */ f(s, { children: /* @__PURE__ */ f("pre", {
+				...h,
+				className: x.pre,
+				children: /* @__PURE__ */ f("code", {
+					ref: y,
+					children: m
+				})
+			}) }) }), /* @__PURE__ */ f(a, {
+				orientation: "horizontal",
+				children: /* @__PURE__ */ f(c, {})
+			})] })
+		]
+	});
+}
+T.displayName = "Code.Block";
+//#endregion
+//#region src/components/code/code.meta.ts
+var E = {
+	name: "Code",
+	category: i.display,
+	status: "stable",
+	namespace: !0,
+	description: "Displays source code inline or in a block, with optional language labels and copying. Also called a code snippet or code block.",
+	origin: "native",
+	internalDependencies: ["ScrollArea"]
+};
+//#endregion
+export { S as a, w as i, T as n, b as o, C as r, E as t };

package/dist/components/app-shell/app-shell.d.ts

@@ -44,7 +44,7 @@ declare function Footer(props: React.ComponentProps<"footer">): import("react/js
 declare namespace Footer {
     var displayName: string;
 }
-declare function Main(props: React.ComponentProps<"main">): import("react/jsx-runtime").JSX.Element;
+declare function Main({ children, ...props }: React.ComponentProps<"main">): import("react/jsx-runtime").JSX.Element;
 declare namespace Main {
     var displayName: string;
 }

package/dist/components/dialog/dialog.d.ts

@@ -0,0 +1,148 @@
+import { Dialog as DialogPrimitive } from '@base-ui/react/dialog';
+import { VariantProps } from 'class-variance-authority';
+import * as ScrollArea from '../scroll-area/scroll-area';
+type HeaderVariant = "primary" | "main" | "support" | "minor";
+declare const dialogTrigger: (props?: ({
+    inline?: boolean | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+declare const dialogStatus: (props?: ({
+    variant?: "positive" | "negative" | "warning" | "info" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+export declare const createHandle: typeof DialogPrimitive.createHandle;
+type RootProps<Payload = unknown> = React.ComponentProps<typeof DialogPrimitive.Root<Payload>>;
+/**
+ * Dialog.Root — container that manages open/closed state.
+ *
+ * @see https://base-ui.com/react/components/dialog
+ * @llm https://base-ui.com/react/components/dialog.md
+ */
+export declare function Root<Payload = unknown>(props: RootProps<Payload>): import("react/jsx-runtime").JSX.Element;
+export declare namespace Root {
+    var displayName: string;
+}
+/** Dialog.Trigger — button that opens the dialog. `inline` styles it as a dashed-underlined term inside running text. */
+export declare function Trigger({ inline, ...props }: React.ComponentProps<typeof DialogPrimitive.Trigger> & VariantProps<typeof dialogTrigger>): import("react/jsx-runtime").JSX.Element;
+export declare namespace Trigger {
+    var displayName: string;
+}
+/** Dialog.Portal — renders backdrop and popup in a portal outside the main document flow. */
+export declare function Portal(props: React.ComponentProps<typeof DialogPrimitive.Portal>): import("react/jsx-runtime").JSX.Element;
+export declare namespace Portal {
+    var displayName: string;
+}
+/** Dialog.Backdrop — flat dark overlay that dims the page behind the dialog. */
+export declare function Backdrop(props: React.ComponentProps<typeof DialogPrimitive.Backdrop>): import("react/jsx-runtime").JSX.Element;
+export declare namespace Backdrop {
+    var displayName: string;
+}
+/** Dialog.Viewport — full-screen container that centres the popup. */
+export declare function Viewport(props: React.ComponentProps<typeof DialogPrimitive.Viewport>): import("react/jsx-runtime").JSX.Element;
+export declare namespace Viewport {
+    var displayName: string;
+}
+interface PopupProps extends React.ComponentProps<typeof DialogPrimitive.Popup> {
+    /**
+     * Width of the window. `full` fills the screen minus a margin.
+     * @default 'md'
+     */
+    size?: "sm" | "md" | "lg" | "full";
+}
+/** Dialog.Popup — the window. Holds Header, Body, and Footer, or any free content. */
+export declare function Popup({ size, ...props }: PopupProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace Popup {
+    var displayName: string;
+}
+type HeaderProps = React.ComponentProps<"div"> & {
+    /**
+     * Colour of the header band. On `primary` the title, description, and close button turn light.
+     * @default 'main'
+     */
+    variant?: HeaderVariant;
+};
+/** Dialog.Header — band at the top of the popup that holds the title, description, and close button. */
+export declare function Header({ variant, ...props }: HeaderProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace Header {
+    var displayName: string;
+}
+/** Dialog.Body — the scrolling region between header and footer, a ScrollArea with the library's thumb and edge fades. */
+export declare function Body({ children, ...props }: React.ComponentProps<typeof ScrollArea.Auto>): import("react/jsx-runtime").JSX.Element;
+export declare namespace Body {
+    var displayName: string;
+}
+/** Dialog.Footer — row of actions pinned to the bottom of the popup. */
+export declare function Footer(props: React.ComponentProps<"div">): import("react/jsx-runtime").JSX.Element;
+export declare namespace Footer {
+    var displayName: string;
+}
+type StatusProps = React.ComponentProps<"div"> & VariantProps<typeof dialogStatus>;
+/**
+ * Dialog.Status — a tinted column at the start of the popup, spanning its full height, that marks the dialog's
+ * status with the variant's glyph. Place it first inside `Dialog.Popup`. Pass children to replace the glyph.
+ * Decorative (`aria-hidden`); the title carries the status.
+ */
+export declare function Status({ variant, children, ...props }: StatusProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace Status {
+    var displayName: string;
+}
+/** Dialog.Title — heading that names the dialog for screen readers, set as `Typo.H2`. Light on a `primary` header. */
+export declare function Title(props: React.ComponentProps<typeof DialogPrimitive.Title>): import("react/jsx-runtime").JSX.Element;
+export declare namespace Title {
+    var displayName: string;
+}
+/** Dialog.Description — supplementary paragraph that describes the dialog for screen readers, set as `Typo.P`. */
+export declare function Description(props: React.ComponentProps<typeof DialogPrimitive.Description>): import("react/jsx-runtime").JSX.Element;
+export declare namespace Description {
+    var displayName: string;
+}
+/**
+ * Dialog.Close — button that closes the dialog. With no `children` and no `render` it renders the library's ghost close
+ * button (an × icon labelled "Close"); otherwise render your own `Button`.
+ */
+export declare function Close(props: React.ComponentProps<typeof DialogPrimitive.Close>): import("react/jsx-runtime").JSX.Element;
+export declare namespace Close {
+    var displayName: string;
+}
+type ComposedProps = Omit<React.ComponentProps<typeof DialogPrimitive.Root>, "children"> & {
+    /** Heading of the dialog. */
+    title: React.ReactNode;
+    /** Short uppercase label above the title. */
+    eyebrow?: React.ReactNode;
+    /** Line of context under the title. */
+    description?: React.ReactNode;
+    /** Adds a `Dialog.Status` with this variant at the start of the popup. */
+    status?: NonNullable<VariantProps<typeof dialogStatus>["variant"]>;
+    /**
+     * Colour of the header band.
+     */
+    headerVariant?: HeaderVariant;
+    /**
+     * Width of the window.
+     */
+    size?: PopupProps["size"];
+    /** Content of the footer, usually buttons. The footer renders only when this is set. */
+    actions?: React.ReactNode;
+    /** Content of the body. */
+    children?: React.ReactNode;
+};
+type SimpleProps = ComposedProps & {
+    /** Element rendered as the trigger, such as a `Button`. Omit it for a controlled dialog. */
+    trigger?: React.ReactElement;
+};
+/**
+ * Dialog.Simple — pre-composed dialog: trigger, header with title, description, optional status and close button, a
+ * scrolling body, and an optional footer. Root props pass through.
+ */
+export declare function Simple({ trigger, headerVariant, size, ...props }: SimpleProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace Simple {
+    var displayName: string;
+}
+type InlineProps = ComposedProps & {
+    /** Text of the trigger, set as an inline term inside running prose. */
+    trigger: React.ReactNode;
+};
+/** Dialog.Inline — like Dialog.Simple, but the trigger is text inside a sentence. */
+export declare function Inline({ trigger, headerVariant, size, ...props }: InlineProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace Inline {
+    var displayName: string;
+}
+export {};

package/dist/components/dialog/dialog.meta.d.ts

@@ -0,0 +1,2 @@
+import { ComponentMeta } from '../../types/meta';
+export declare const dialogMeta: ComponentMeta;

package/dist/components/dialog/index.d.ts

@@ -0,0 +1,2 @@
+export * as Dialog from './dialog';
+export { dialogMeta } from './dialog.meta';

package/dist/components/drawer/drawer.d.ts

@@ -63,7 +63,7 @@ export declare namespace Popup {
     var displayName: string;
 }
 /** Drawer.Content — scrollable content wrapper inside the popup. */
-export declare function Content(props: React.ComponentProps<typeof DrawerPrimitive.Content>): import("react/jsx-runtime").JSX.Element;
+export declare function Content({ children, ...props }: React.ComponentProps<typeof DrawerPrimitive.Content>): import("react/jsx-runtime").JSX.Element;
 export declare namespace Content {
     var displayName: string;
 }

package/dist/components/scroll-area/index.d.ts

@@ -0,0 +1,2 @@
+export * as ScrollArea from './scroll-area';
+export { scrollAreaMeta } from './scroll-area.meta';

package/dist/components/scroll-area/scroll-area.d.ts

@@ -0,0 +1,49 @@
+import { ScrollArea as ScrollAreaPrimitive } from '@base-ui/react/scroll-area';
+/**
+ * ScrollArea.Root — groups the viewport and its scrollbars. Give it a height or max-height.
+ *
+ * @see https://base-ui.com/react/components/scroll-area
+ * @llm https://base-ui.com/react/components/scroll-area.md
+ */
+export declare function Root(props: React.ComponentProps<typeof ScrollAreaPrimitive.Root>): import("react/jsx-runtime").JSX.Element;
+export declare namespace Root {
+    var displayName: string;
+}
+/** ScrollArea.Viewport — the scrolling box. It fades its content out at each edge with more to scroll. */
+export declare function Viewport(props: React.ComponentProps<typeof ScrollAreaPrimitive.Viewport>): import("react/jsx-runtime").JSX.Element;
+export declare namespace Viewport {
+    var displayName: string;
+}
+/** ScrollArea.Content — wraps the scrolled content so the viewport can measure it. */
+export declare function Content(props: React.ComponentProps<typeof ScrollAreaPrimitive.Content>): import("react/jsx-runtime").JSX.Element;
+export declare namespace Content {
+    var displayName: string;
+}
+/** ScrollArea.Scrollbar — overlay bar that shows while the area is hovered or scrolling. */
+export declare function Scrollbar(props: React.ComponentProps<typeof ScrollAreaPrimitive.Scrollbar>): import("react/jsx-runtime").JSX.Element;
+export declare namespace Scrollbar {
+    var displayName: string;
+}
+/** ScrollArea.Thumb — the draggable part of the scrollbar. */
+export declare function Thumb(props: React.ComponentProps<typeof ScrollAreaPrimitive.Thumb>): import("react/jsx-runtime").JSX.Element;
+export declare namespace Thumb {
+    var displayName: string;
+}
+/** ScrollArea.Corner — the square where a vertical and a horizontal scrollbar meet. */
+export declare function Corner(props: React.ComponentProps<typeof ScrollAreaPrimitive.Corner>): import("react/jsx-runtime").JSX.Element;
+export declare namespace Corner {
+    var displayName: string;
+}
+interface AutoProps extends React.ComponentProps<typeof ScrollAreaPrimitive.Root> {
+    /**
+     * Which scrollbars to render. `both` also adds the Corner; `none` scrolls and fades without a visible bar.
+     * @default 'vertical'
+     */
+    orientation?: "vertical" | "horizontal" | "both" | "none";
+}
+/** ScrollArea.Auto — Root, Viewport, Content, and the scrollbars for `orientation`, around `children`. */
+export declare function Auto({ orientation, children, ...props }: AutoProps): import("react/jsx-runtime").JSX.Element;
+export declare namespace Auto {
+    var displayName: string;
+}
+export {};

package/dist/components/scroll-area/scroll-area.meta.d.ts

@@ -0,0 +1,2 @@
+import { ComponentMeta } from '../../types/meta';
+export declare const scrollAreaMeta: ComponentMeta;

package/dist/index.d.ts

@@ -15,10 +15,12 @@ export { Toggle, toggleMeta } from './components/toggle';
 export { ToggleGroup, toggleGroupMeta } from './components/toggle-group';
 export { AppShell, appShellMeta } from './components/app-shell';
 export { Card, cardMeta } from './components/card';
+export { Dialog, dialogMeta } from './components/dialog';
 export { Drawer, drawerMeta } from './components/drawer';
 export { Popover, popoverMeta } from './components/popover';
 export { Prose, proseMeta } from './components/prose';
 export { Row, rowMeta } from './components/row';
+export { ScrollArea, scrollAreaMeta } from './components/scroll-area';
 export { Separator, separatorMeta } from './components/separator';
 export { Stack, stackMeta } from './components/stack';
 export { AccountCard, accountCardMeta } from './components/account-card';