@imfusion/web-ui 0.7.2-dev.6.g1f49e9fa → 0.8.1-dev.1.g11d9ffbe

package/CHANGELOG.md

@@ -4,6 +4,99 @@
 
 ### Added
 
+- Components — Nikolaus Brunner <brunner@imfusion.com>
+  - `Avatar` shows a person's photo, their initials, or a person glyph, in three sizes and an on-color context.
+  - `AccountCard` links to the signed-in person's account with an avatar, a title, a description, and a trailing action.
+
+---
+
+## `0.8.0` &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 2026.10.01
+
+### Highlights
+
+#### The layout owns spacing
+
+Web UI components have no outer margin. The parent sets the space between them: `Stack` and `Row` gaps in UI, and the new
+`Prose` for long-form text. A component now sits at the same distance from its neighbours in every layout, where a margin
+used to add to the gap inside a `Stack`, a `Row`, or a card.
+
+```tsx
+import { Callout, Prose, Stack, Typo } from "@imfusion/web-ui";
+
+<Stack gap="3">
+  <Typo.P>Your study is ready.</Typo.P>
+  <Callout.Root>…</Callout.Root>
+</Stack>
+
+<Prose>
+  <Typo.H2>Export</Typo.H2>
+  <Typo.P>Pick a format, then a destination.</Typo.P>
+</Prose>
+```
+
+`Prose` spaces headings, paragraphs, lists, `Code.Block`, `Table.Root`, `Callout.Root`, and `Separator` by their role, and
+its first and last child sit flush with its edges. It is `experimental`. `imf-web-ui-conventions` has a Spacing section,
+`imf-web-ui-audit` checks it, and `imf-web-ui-update` finds the call sites a style-only change touches.
+
+#### New and updated components
+
+- `Prose` is new. It spaces long-form text and the blocks inside it.
+- Read-only `Input`, `NumberField`, and `Select` share a dashed border, muted text, and no fill, so a locked value reads
+  apart from an editable or a disabled one. A read-only search `Input` has no clear button.
+- `NavigationMenu` flyout text and padding scale with the fluid body size, and `NavigationMenu.Link` has no hover arrow.
+
+#### Link a local checkout
+
+The `localWebUILink` Vite plugin dedupes the library's peer dependencies in an app that links a local Web UI checkout.
+
+#### Important fixes
+
+- `WebUIProvider` and `useColorScheme` render on the server and hydrate from the stored and OS color scheme.
+
+#### Migrating from 0.7
+
+Typo members have no margin and no `spacing` prop. Wrap long-form text in `Prose`:
+
+```diff
+- <div>
++ <Prose>
+    <Typo.H2>Export</Typo.H2>
+    <Typo.P>Pick a format, then a destination.</Typo.P>
+- </div>
++ </Prose>
+```
+
+Delete `spacing="none"`, which is now the only behavior:
+
+```diff
+- <Typo.P spacing="none">Your study is ready.</Typo.P>
++ <Typo.P>Your study is ready.</Typo.P>
+```
+
+`Callout.Root`, `Table.Root`, `Code.Block`, and `Separator` have no margin either. Space them with a gap, or put them inside
+`Prose`:
+
+```diff
+- <div>
++ <Stack gap="3">
+    <Callout.Root>…</Callout.Root>
+-   <Separator spacing="large" />
++   <Separator />
+    <Table.Root>…</Table.Root>
+- </div>
++ </Stack>
+```
+
+### Breaking
+
+- **Breaking:** Web UI components have no outer margin. `Stack` and `Row` gaps space UI, and `Prose` spaces long-form text. — Nikolaus Brunner <brunner@imfusion.com>
+  - Block `Typo` members (`Hero`, `H1`–`H4`, `P`, `Lead`, `Blockquote`, and the lists) have no default margin and no
+    `spacing` prop.
+  - `Callout.Root`, `Table.Root`, and `Code.Block` have no bottom margin.
+  - `Separator` has no `spacing` prop.
+
+### Added
+
 - Storybook — Nikolaus Brunner <brunner@imfusion.com>
   - The token drawer offers Kode Mono as a mono font.
 
@@ -11,19 +104,29 @@
 
 - Components — Nikolaus Brunner <brunner@imfusion.com>
   - `Drawer` draws its open-edge border at `--imf-ui-border-size-1`.
+  - `NavigationMenu.InlineSubmenu` spaces its rail and detail pane with one flyout padding.
 - Agent skills — Nikolaus Brunner <brunner@imfusion.com>
+  - `imf-web-ui-conventions` says when a locked field uses `readOnly`, `disabled`, or plain text.
   - `imf-web-ui-update` measures the delta from a prerelease baseline by diffing the old package's types and styles.
+  - The component and story dev skills name the Storybook CLI command for each lookup and check, and route only pixels, DOM,
+    focus, and console checks to Chrome DevTools.
+  - `web-ui-dev-new-component` checks existing primitives before any upstream lookup, for a URL or a description, and routes
+    a partial match to `web-ui-dev-update-component`.
 
 ### Fixed
 
 - Storybook — Nikolaus Brunner <brunner@imfusion.com>
   - Nested sidebar groups and components indent under their parent group.
+  - Sidebar components line up with the stories and docs beside them.
+  - The showcase keeps a gap between its content and the docked token drawer.
+  - The showcase docks the token drawer from the `xl` breakpoint, so its navigation strip fits beside it.
   - Font choices in the token drawer persist in the URL.
   - The sidebar and panes stay visible while the sidebar is resized.
   - The sidebar keeps a minimum width that fits its section labels.
   - The preview stays dark while a page loads in dark mode.
 - Agent skills — Nikolaus Brunner <brunner@imfusion.com>
   - `npx web-ui install skills` formats the skill version markers with the project's Prettier.
+  - `imf-web-ui-audit` has a checklist box for every tooling section, including Vite plugins.
 
 ---
 

package/README.md

@@ -87,3 +87,35 @@ The main development skills are:
 | `/web-ui-dev-claude-design-sync`   | Update the design system in Claude Design.       |
 | `/web-ui-dev-teardown-worktree`    | Remove a finished worktree.                      |
 | `/web-ui-dev-mcp`                  | Recover one optional MCP capability.             |
+
+### Work on it from a consumer app
+
+To change the library while running an app that uses it, point the app's dependency at your checkout:
+
+```json
+"@imfusion/web-ui": "file:../web-ui"
+```
+
+Run `npm install` in the app, then keep `npm run dev:lib` running here. The package resolves to `dist/`, so the app resolves
+nothing until the first watch build has finished, and sees each later change once the rebuild has written it.
+
+npm links the checkout instead of copying it. Without help, the app then loads two copies of React, its own and the one in
+this checkout's `node_modules`, and every hook fails with "Invalid hook call". Register `localWebUILink` in the app's Vite
+config to prevent that:
+
+```ts
+import { localWebUILink } from "@imfusion/web-ui/vite";
+
+export default defineConfig({
+  plugins: [react(), localWebUILink()]
+});
+```
+
+It dedupes every peer dependency of the library, including `@imfusion/sdk` and `@imfusion/sdk-react`. For an installed
+package it does nothing, so it can stay in the config.
+
+It covers the browser in development and in the build. Server rendering, including React Router prerendering, still loads
+dependencies through Node, which picks the checkout's React. Base UI's `use-sync-external-store` dependency is CommonJS, so
+Popover, Select, and other stateful parts can still fail on the server.
+
+Change the dependency back before you commit the app.

package/dist/components/account-card/account-card.d.ts

@@ -0,0 +1,53 @@
+import { useRender } from '@base-ui/react/use-render';
+import { VariantProps } from 'class-variance-authority';
+import * as AvatarParts from '../avatar/avatar';
+declare const root: (props?: ({
+    context?: "default" | "oncolor" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+type RootProps = useRender.ComponentProps<"a"> & VariantProps<typeof root>;
+/**
+ * AccountCard.Root — the link to the signed-in person's account, holding `AccountCard.Avatar`, `AccountCard.Title`, and
+ * `AccountCard.Description`. Pass a router link through `render`. `aria-current="page"` marks it current with a tint and
+ * an inset rule. Its accessible name is the title and description; the avatar stays decorative.
+ *
+ * Place `AccountCard.Action` beside the root, not inside it: a link cannot contain a button.
+ */
+declare function Root({ 
+/** Explicit saturated-surface context; this is never inferred from an ancestor. */
+context, render, ...props }: RootProps): import("react/jsx-runtime").JSX.Element;
+declare namespace Root {
+    var displayName: string;
+}
+type AvatarProps = React.HTMLAttributes<HTMLSpanElement> & {
+    /** The person's photo. Until it loads, and when it fails, the initials or the person glyph show instead. */
+    src?: string;
+    /** The avatar size. */
+    size?: React.ComponentProps<typeof AvatarParts.Root>["size"];
+};
+/**
+ * AccountCard.Avatar — a decorative `Avatar` in the card's context. Its children are the initials; without them it shows
+ * a person glyph.
+ */
+declare function Avatar({ src, size, children, ...props }: AvatarProps): import("react/jsx-runtime").JSX.Element;
+declare namespace Avatar {
+    var displayName: string;
+}
+/** AccountCard.Title — the account's name, or its email until a name exists. Truncates to one line. */
+declare function Title(props: React.HTMLAttributes<HTMLSpanElement>): import("react/jsx-runtime").JSX.Element;
+declare namespace Title {
+    var displayName: string;
+}
+/** AccountCard.Description — a second line such as organization and role. Truncates to one line. */
+declare function Description(props: React.HTMLAttributes<HTMLSpanElement>): import("react/jsx-runtime").JSX.Element;
+declare namespace Description {
+    var displayName: string;
+}
+/**
+ * AccountCard.Action — a trailing slot beside `AccountCard.Root`, such as a ghost icon `Button` that logs out. The
+ * button carries its own `aria-label` and its own `context`.
+ */
+declare function Action(props: React.HTMLAttributes<HTMLDivElement>): import("react/jsx-runtime").JSX.Element;
+declare namespace Action {
+    var displayName: string;
+}
+export { Root, Avatar, Title, Description, Action };

package/dist/components/account-card/account-card.meta.d.ts

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

package/dist/components/account-card/index.d.ts

@@ -0,0 +1,2 @@
+export * as AccountCard from './account-card';
+export { accountCardMeta } from './account-card.meta';

package/dist/components/avatar/avatar.d.ts

@@ -0,0 +1,40 @@
+import { Avatar as AvatarPrimitive } from '@base-ui/react/avatar';
+import { VariantProps } from 'class-variance-authority';
+declare const root: (props?: ({
+    size?: "sm" | "md" | "lg" | null | undefined;
+    context?: "default" | "oncolor" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+interface RootProps extends React.ComponentProps<typeof AvatarPrimitive.Root>, VariantProps<typeof root> {
+}
+/**
+ * Avatar.Root — a round badge that stands for a person. Also called a profile picture or user badge.
+ *
+ * Without `aria-label` or `aria-labelledby` it is decorative and hidden from assistive tech, for use next to a visible
+ * name. With a label it is announced as an image with that name.
+ *
+ * @doc https://base-ui.com/react/components/avatar
+ * @llm https://base-ui.com/react/components/avatar.md
+ */
+declare function Root({ size, 
+/** Explicit saturated-surface context; this is never inferred from an ancestor. */
+context, ...props }: RootProps): import("react/jsx-runtime").JSX.Element;
+declare namespace Root {
+    var displayName: string;
+}
+/**
+ * Avatar.Fallback — the initials the consumer passes, one or two letters. Without children it shows a person glyph.
+ * It derives nothing from a name or email.
+ */
+declare function Fallback({ children, ...props }: React.ComponentProps<typeof AvatarPrimitive.Fallback>): import("react/jsx-runtime").JSX.Element;
+declare namespace Fallback {
+    var displayName: string;
+}
+/**
+ * Avatar.Image — the person's photo, cropped to the circle. It shows once `src` has loaded; until then, and when it
+ * fails, `Avatar.Fallback` shows instead.
+ */
+declare function Image({ alt, ...props }: React.ComponentProps<typeof AvatarPrimitive.Image>): import("react/jsx-runtime").JSX.Element;
+declare namespace Image {
+    var displayName: string;
+}
+export { Root, Image, Fallback };

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

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

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

@@ -0,0 +1,2 @@
+export * as Avatar from './avatar';
+export { avatarMeta } from './avatar.meta';

package/dist/components/navigation-menu/subs/link.d.ts

@@ -4,11 +4,8 @@ import { UpstreamLink } from './shared';
  * NavigationMenu.Link — a top-strip (rail) link: a peer of `Trigger` for a
  * section that navigates directly instead of opening a flyout. Renders an `<a>`.
  * For a link inside a flyout, use `NavigationMenu.FlyoutLink`.
- *
- * A trailing `ArrowRight` slides in on hover/focus. When a custom `render` is
- * supplied the icon is omitted — the consumer's element owns its content.
  */
-export declare function Link({ children, render, ...props }: React.ComponentProps<typeof NavigationMenuPrimitive.Link>): import("react/jsx-runtime").JSX.Element;
+export declare function Link(props: React.ComponentProps<typeof NavigationMenuPrimitive.Link>): import("react/jsx-runtime").JSX.Element;
 export declare namespace Link {
     var displayName: string;
 }

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

@@ -0,0 +1,2 @@
+export { Prose } from './prose';
+export { proseMeta } from './prose.meta';

package/dist/components/prose/prose.d.ts

@@ -0,0 +1 @@
+export declare function Prose(props: React.HTMLAttributes<HTMLDivElement>): import("react/jsx-runtime").JSX.Element;

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

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

package/dist/components/separator/separator.d.ts

@@ -2,7 +2,6 @@ import { Separator as SeparatorPrimitive } from '@base-ui/react/separator';
 import { VariantProps } from 'class-variance-authority';
 declare const separator: (props?: ({
     variant?: "solid" | "dashed" | "dotted" | null | undefined;
-    spacing?: "none" | "small" | "medium" | "large" | "spacious" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
 interface Props extends React.ComponentProps<typeof SeparatorPrimitive>, VariantProps<typeof separator> {
 }
@@ -12,5 +11,5 @@ interface Props extends React.ComponentProps<typeof SeparatorPrimitive>, Variant
  * @see https://base-ui.com/react/components/separator
  * @llm https://base-ui.com/react/components/separator.md
  */
-export declare function Separator({ orientation, variant, spacing, ...props }: Props): import("react/jsx-runtime").JSX.Element;
+export declare function Separator({ orientation, variant, ...props }: Props): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/typo/typo.d.ts

@@ -4,54 +4,50 @@ import { Code } from '../code';
 declare const typo: (props?: ({
     variant?: "primary" | "positive" | "negative" | "oncolor" | "main" | "support" | "minor" | "brand" | "warning" | "info" | "accent-1" | "accent-2" | "accent-3" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
-declare const spacingVariants: (props?: ({
-    spacing?: "none" | "default" | null | undefined;
-} & import('class-variance-authority/types').ClassProp) | undefined) => string;
 type TypoProps = VariantProps<typeof typo>;
-type SpacingProps = VariantProps<typeof spacingVariants>;
-type HeadingProps = useRender.ComponentProps<"h1"> & TypoProps & SpacingProps;
+type HeadingProps = useRender.ComponentProps<"h1"> & TypoProps;
 type LongHeadingProps = HeadingProps & {
     /** Whether lines after the first use a translucent text color. */
     fadeAfterFirstLine?: boolean;
 };
-type ParagraphProps = useRender.ComponentProps<"p"> & TypoProps & SpacingProps;
+type ParagraphProps = useRender.ComponentProps<"p"> & TypoProps;
 export type TypoLinkKind = "external" | "internal";
 type LinkProps = useRender.ComponentProps<"a"> & TypoProps & {
     /** Link target scope. `"external"` (default) opens in a new tab; `"internal"` stays in the current tab. */
     kind?: TypoLinkKind;
 };
 /** Typo.Hero — oversized page heading. */
-export declare function Hero({ variant, spacing, fadeAfterFirstLine, render, ...props }: LongHeadingProps): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
+export declare function Hero({ variant, fadeAfterFirstLine, render, ...props }: LongHeadingProps): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
 export declare namespace Hero {
     var displayName: string;
 }
 /** Typo.H1 — top-level page heading. */
-export declare function H1({ variant, spacing, fadeAfterFirstLine, render, ...props }: LongHeadingProps): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
+export declare function H1({ variant, fadeAfterFirstLine, render, ...props }: LongHeadingProps): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
 export declare namespace H1 {
     var displayName: string;
 }
 /** Typo.H2 — section heading. */
-export declare function H2({ variant, spacing, fadeAfterFirstLine, render, ...props }: LongHeadingProps): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
+export declare function H2({ variant, fadeAfterFirstLine, render, ...props }: LongHeadingProps): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
 export declare namespace H2 {
     var displayName: string;
 }
 /** Typo.H3 — sub-section heading. */
-export declare function H3({ variant, spacing, render, ...props }: HeadingProps): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
+export declare function H3({ variant, render, ...props }: HeadingProps): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
 export declare namespace H3 {
     var displayName: string;
 }
 /** Typo.H4 — minor heading. */
-export declare function H4({ variant, spacing, render, ...props }: HeadingProps): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
+export declare function H4({ variant, render, ...props }: HeadingProps): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
 export declare namespace H4 {
     var displayName: string;
 }
 /** Typo.P — body paragraph. */
-export declare function P({ variant, spacing, render, ...props }: ParagraphProps): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
+export declare function P({ variant, render, ...props }: ParagraphProps): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
 export declare namespace P {
     var displayName: string;
 }
 /** Typo.Lead — emphasised intro paragraph. */
-export declare function Lead({ variant, spacing, render, ...props }: ParagraphProps): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
+export declare function Lead({ variant, render, ...props }: ParagraphProps): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
 export declare namespace Lead {
     var displayName: string;
 }
@@ -66,7 +62,7 @@ export declare namespace Small {
     var displayName: string;
 }
 /** Typo.Blockquote — pulled quotation. */
-export declare function Blockquote({ variant, spacing, render, ...props }: useRender.ComponentProps<"blockquote"> & TypoProps & SpacingProps): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
+export declare function Blockquote({ variant, render, ...props }: useRender.ComponentProps<"blockquote"> & TypoProps): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
 export declare namespace Blockquote {
     var displayName: string;
 }
@@ -89,12 +85,12 @@ export declare namespace Link {
     var displayName: string;
 }
 /** Typo.OrderedList — numbered list. */
-export declare function OrderedList({ variant, spacing, render, ...props }: useRender.ComponentProps<"ol"> & TypoProps & SpacingProps): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
+export declare function OrderedList({ variant, render, ...props }: useRender.ComponentProps<"ol"> & TypoProps): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
 export declare namespace OrderedList {
     var displayName: string;
 }
 /** Typo.UnorderedList — bulleted list. */
-export declare function UnorderedList({ variant, spacing, render, ...props }: useRender.ComponentProps<"ul"> & TypoProps & SpacingProps): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
+export declare function UnorderedList({ variant, render, ...props }: useRender.ComponentProps<"ul"> & TypoProps): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
 export declare namespace UnorderedList {
     var displayName: string;
 }

package/dist/index.d.ts

@@ -15,9 +15,12 @@ export { AppShell, appShellMeta } from './components/app-shell';
 export { Card, cardMeta } from './components/card';
 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 { Separator, separatorMeta } from './components/separator';
 export { Stack, stackMeta } from './components/stack';
+export { AccountCard, accountCardMeta } from './components/account-card';
+export { Avatar, avatarMeta } from './components/avatar';
 export { Callout, calloutMeta } from './components/callout';
 export { Chip, chipMeta } from './components/chip';
 export { Code, codeMeta } from './components/code';