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

package/src/docgen/doc.gen.json

@@ -1,4 +1,70 @@
 {
+  "account-card": {
+    "root": {
+      "name": "AccountCard.Root",
+      "description": "AccountCard.Root — the link to the signed-in person's account, holding `AccountCard.Avatar`, `AccountCard.Title`, and\n`AccountCard.Description`. Pass a router link through `render`. `aria-current=\"page\"` marks it current with a tint and\nan inset rule. Its accessible name is the title and description; the avatar stays decorative.\n\nPlace `AccountCard.Action` beside the root, not inside it: a link cannot contain a button.",
+      "props": [
+        {
+          "name": "context",
+          "required": false,
+          "type": "\"default\" | \"oncolor\" | null",
+          "defaultValue": "default",
+          "description": ""
+        },
+        {
+          "name": "ref",
+          "required": false,
+          "type": "Ref<HTMLAnchorElement>",
+          "defaultValue": null,
+          "description": "Allows getting a ref to the component instance.\nOnce the component unmounts, React will set `ref.current` to `null`\n(or call the ref with `null` if you passed a callback ref).\n@see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}"
+        },
+        {
+          "name": "render",
+          "required": false,
+          "type": "| ReactElement<\n    unknown,\n    string | JSXElementConstructor<any>\n  >\n| ComponentRenderFn<HTMLProps, {}>",
+          "defaultValue": null,
+          "description": "Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+        }
+      ]
+    },
+    "subComponents": [
+      {
+        "name": "AccountCard.Action",
+        "description": "AccountCard.Action — a trailing slot beside `AccountCard.Root`, such as a ghost icon `Button` that logs out. The\nbutton carries its own `aria-label` and its own `context`.",
+        "props": []
+      },
+      {
+        "name": "AccountCard.Avatar",
+        "description": "AccountCard.Avatar — a decorative `Avatar` in the card's context. Its children are the initials; without them it shows\na person glyph.",
+        "props": [
+          {
+            "name": "size",
+            "required": false,
+            "type": "\"sm\" | \"md\" | \"lg\" | null",
+            "defaultValue": "md",
+            "description": "The avatar size."
+          },
+          {
+            "name": "src",
+            "required": false,
+            "type": "string",
+            "defaultValue": null,
+            "description": "The person's photo. Until it loads, and when it fails, the initials or the person glyph show instead."
+          }
+        ]
+      },
+      {
+        "name": "AccountCard.Description",
+        "description": "AccountCard.Description — a second line such as organization and role. Truncates to one line.",
+        "props": []
+      },
+      {
+        "name": "AccountCard.Title",
+        "description": "AccountCard.Title — the account's name, or its email until a name exists. Truncates to one line.",
+        "props": []
+      }
+    ]
+  },
   "app-shell": {
     "root": {
       "name": "AppShell.Root",
@@ -62,6 +128,140 @@
       }
     ]
   },
+  "avatar": {
+    "root": {
+      "name": "Avatar.Root",
+      "description": "Avatar.Root — a round badge that stands for a person. Also called a profile picture or user badge.\n\nWithout `aria-label` or `aria-labelledby` it is decorative and hidden from assistive tech, for use next to a visible\nname. With a label it is announced as an image with that name.",
+      "props": [
+        {
+          "name": "className",
+          "required": false,
+          "type": "string | ((state: AvatarRootState) => string)",
+          "defaultValue": null,
+          "description": "CSS class applied to the element, or a function that\nreturns a class based on the component's state."
+        },
+        {
+          "name": "context",
+          "required": false,
+          "type": "\"default\" | \"oncolor\" | null",
+          "defaultValue": "default",
+          "description": ""
+        },
+        {
+          "name": "ref",
+          "required": false,
+          "type": "Ref<HTMLSpanElement>",
+          "defaultValue": null,
+          "description": "Allows getting a ref to the component instance.\nOnce the component unmounts, React will set `ref.current` to `null`\n(or call the ref with `null` if you passed a callback ref).\n@see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}"
+        },
+        {
+          "name": "render",
+          "required": false,
+          "type": "| ReactElement<\n    unknown,\n    string | JSXElementConstructor<any>\n  >\n| ComponentRenderFn<HTMLProps, AvatarRootState>",
+          "defaultValue": null,
+          "description": "Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+        },
+        {
+          "name": "size",
+          "required": false,
+          "type": "\"sm\" | \"md\" | \"lg\" | null",
+          "defaultValue": "md",
+          "description": ""
+        },
+        {
+          "name": "style",
+          "required": false,
+          "type": "| CSSProperties\n| ((state: AvatarRootState) => CSSProperties)",
+          "defaultValue": null,
+          "description": "Style applied to the element, or a function that\nreturns a style object based on the component's state."
+        }
+      ]
+    },
+    "subComponents": [
+      {
+        "name": "Avatar.Fallback",
+        "description": "Avatar.Fallback — the initials the consumer passes, one or two letters. Without children it shows a person glyph.\nIt derives nothing from a name or email.",
+        "props": [
+          {
+            "name": "className",
+            "required": false,
+            "type": "string | ((state: AvatarFallbackState) => string)",
+            "defaultValue": null,
+            "description": "CSS class applied to the element, or a function that\nreturns a class based on the component's state."
+          },
+          {
+            "name": "delay",
+            "required": false,
+            "type": "number",
+            "defaultValue": null,
+            "description": "How long to wait before showing the fallback. Specified in milliseconds."
+          },
+          {
+            "name": "ref",
+            "required": false,
+            "type": "Ref<HTMLSpanElement>",
+            "defaultValue": null,
+            "description": "Allows getting a ref to the component instance.\nOnce the component unmounts, React will set `ref.current` to `null`\n(or call the ref with `null` if you passed a callback ref).\n@see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}"
+          },
+          {
+            "name": "render",
+            "required": false,
+            "type": "| ReactElement<\n    unknown,\n    string | JSXElementConstructor<any>\n  >\n| ComponentRenderFn<HTMLProps, AvatarFallbackState>",
+            "defaultValue": null,
+            "description": "Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+          },
+          {
+            "name": "style",
+            "required": false,
+            "type": "| CSSProperties\n| ((state: AvatarFallbackState) => CSSProperties)",
+            "defaultValue": null,
+            "description": "Style applied to the element, or a function that\nreturns a style object based on the component's state."
+          }
+        ]
+      },
+      {
+        "name": "Avatar.Image",
+        "description": "Avatar.Image — the person's photo, cropped to the circle. It shows once `src` has loaded; until then, and when it\nfails, `Avatar.Fallback` shows instead.",
+        "props": [
+          {
+            "name": "className",
+            "required": false,
+            "type": "string | ((state: AvatarImageState) => string)",
+            "defaultValue": null,
+            "description": "CSS class applied to the element, or a function that\nreturns a class based on the component's state."
+          },
+          {
+            "name": "onLoadingStatusChange",
+            "required": false,
+            "type": "(status: ImageLoadingStatus) => void",
+            "defaultValue": null,
+            "description": "Callback fired when the loading status changes."
+          },
+          {
+            "name": "ref",
+            "required": false,
+            "type": "Ref<HTMLSpanElement>",
+            "defaultValue": null,
+            "description": "Allows getting a ref to the component instance.\nOnce the component unmounts, React will set `ref.current` to `null`\n(or call the ref with `null` if you passed a callback ref).\n@see {@link https://react.dev/learn/referencing-values-with-refs#refs-and-the-dom React Docs}"
+          },
+          {
+            "name": "render",
+            "required": false,
+            "type": "| ReactElement<\n    unknown,\n    string | JSXElementConstructor<any>\n  >\n| ComponentRenderFn<HTMLProps, AvatarImageState>",
+            "defaultValue": null,
+            "description": "Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
+          },
+          {
+            "name": "style",
+            "required": false,
+            "type": "| CSSProperties\n| ((state: AvatarImageState) => CSSProperties)",
+            "defaultValue": null,
+            "description": "Style applied to the element, or a function that\nreturns a style object based on the component's state."
+          }
+        ]
+      }
+    ]
+  },
   "button": {
     "root": {
       "name": "Button",
@@ -2461,7 +2661,7 @@
       },
       {
         "name": "NavigationMenu.Link",
-        "description": "NavigationMenu.Link — a top-strip (rail) link: a peer of `Trigger` for a\nsection that navigates directly instead of opening a flyout. Renders an `<a>`.\nFor a link inside a flyout, use `NavigationMenu.FlyoutLink`.\n\nA trailing `ArrowRight` slides in on hover/focus. When a custom `render` is\nsupplied the icon is omitted — the consumer's element owns its content.",
+        "description": "NavigationMenu.Link — a top-strip (rail) link: a peer of `Trigger` for a\nsection that navigates directly instead of opening a flyout. Renders an `<a>`.\nFor a link inside a flyout, use `NavigationMenu.FlyoutLink`.",
         "props": [
           {
             "name": "active",
@@ -4250,6 +4450,14 @@
       }
     ]
   },
+  "prose": {
+    "root": {
+      "name": "Prose",
+      "description": "",
+      "props": []
+    },
+    "subComponents": []
+  },
   "row": {
     "root": {
       "name": "Row",
@@ -5306,13 +5514,6 @@
           "defaultValue": null,
           "description": "Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
         },
-        {
-          "name": "spacing",
-          "required": false,
-          "type": "| \"small\"\n| \"none\"\n| \"medium\"\n| \"large\"\n| \"spacious\"\n| null",
-          "defaultValue": "none",
-          "description": ""
-        },
         {
           "name": "style",
           "required": false,
@@ -7559,13 +7760,6 @@
             "defaultValue": null,
             "description": "Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
           },
-          {
-            "name": "spacing",
-            "required": false,
-            "type": "\"default\" | \"none\" | null",
-            "defaultValue": "default",
-            "description": ""
-          },
           {
             "name": "variant",
             "required": false,
@@ -7627,13 +7821,6 @@
             "defaultValue": null,
             "description": "Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
           },
-          {
-            "name": "spacing",
-            "required": false,
-            "type": "\"default\" | \"none\" | null",
-            "defaultValue": "default",
-            "description": ""
-          },
           {
             "name": "variant",
             "required": false,
@@ -7668,13 +7855,6 @@
             "defaultValue": null,
             "description": "Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
           },
-          {
-            "name": "spacing",
-            "required": false,
-            "type": "\"default\" | \"none\" | null",
-            "defaultValue": "default",
-            "description": ""
-          },
           {
             "name": "variant",
             "required": false,
@@ -7702,13 +7882,6 @@
             "defaultValue": null,
             "description": "Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
           },
-          {
-            "name": "spacing",
-            "required": false,
-            "type": "\"default\" | \"none\" | null",
-            "defaultValue": "default",
-            "description": ""
-          },
           {
             "name": "variant",
             "required": false,
@@ -7736,13 +7909,6 @@
             "defaultValue": null,
             "description": "Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
           },
-          {
-            "name": "spacing",
-            "required": false,
-            "type": "\"default\" | \"none\" | null",
-            "defaultValue": "default",
-            "description": ""
-          },
           {
             "name": "variant",
             "required": false,
@@ -7777,13 +7943,6 @@
             "defaultValue": null,
             "description": "Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
           },
-          {
-            "name": "spacing",
-            "required": false,
-            "type": "\"default\" | \"none\" | null",
-            "defaultValue": "default",
-            "description": ""
-          },
           {
             "name": "variant",
             "required": false,
@@ -7872,13 +8031,6 @@
             "defaultValue": null,
             "description": "Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
           },
-          {
-            "name": "spacing",
-            "required": false,
-            "type": "\"default\" | \"none\" | null",
-            "defaultValue": "default",
-            "description": ""
-          },
           {
             "name": "variant",
             "required": false,
@@ -7940,13 +8092,6 @@
             "defaultValue": null,
             "description": "Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
           },
-          {
-            "name": "spacing",
-            "required": false,
-            "type": "\"default\" | \"none\" | null",
-            "defaultValue": "default",
-            "description": ""
-          },
           {
             "name": "variant",
             "required": false,
@@ -7974,13 +8119,6 @@
             "defaultValue": null,
             "description": "Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
           },
-          {
-            "name": "spacing",
-            "required": false,
-            "type": "\"default\" | \"none\" | null",
-            "defaultValue": "default",
-            "description": ""
-          },
           {
             "name": "variant",
             "required": false,
@@ -8035,13 +8173,6 @@
             "defaultValue": null,
             "description": "Allows you to replace the component's HTML element\nwith a different tag, or compose it with another component.\n\nAccepts a `ReactElement` or a function that returns the element to render."
           },
-          {
-            "name": "spacing",
-            "required": false,
-            "type": "\"default\" | \"none\" | null",
-            "defaultValue": "default",
-            "description": ""
-          },
           {
             "name": "variant",
             "required": false,

package/src/llms/llms.gen.txt

@@ -9,11 +9,22 @@ reading the whole file. `further reading` links (when present) point at
 the upstream library's own docs for usage/anatomy/composition — not for
 props, which always live in the docgen file above.
 
+## AccountCard
+- category: Display, status: experimental
+Link to the signed-in person's account, with avatar, name or email, and a second line such as organization and role. Also called an ID card or user row; for a bare person badge, use Avatar.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .account-card (jq: jq '.account-card' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+
 ## AppShell
 - category: Layout, status: stable
 Application layout shell for a header, sidebars, footer, and scrolling main area. Also called an app layout or dashboard shell; sizing is CSS-driven and sidebars can become sliding panels on small screens.
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .app-shell (jq: jq '.app-shell' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 
+## Avatar
+- category: Display, status: experimental
+Round badge that stands for a person, showing their photo, their initials, or a person glyph. Also called a profile picture or user badge; for a signed-in account row with a name, use AccountCard.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .avatar (jq: jq '.avatar' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+- further reading (usage/anatomy, not props): https://base-ui.com/react/components/avatar.md
+
 ## Button
 - category: Buttons, status: stable
 Triggers an action such as submit, confirm, cancel, navigate, or delete. Also called a CTA or action button; variants and sizes communicate its importance.
@@ -125,6 +136,11 @@ Floating panel anchored to a trigger for contextual content, quick forms, or act
 - props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .popover (jq: jq '.popover' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
 - further reading (usage/anatomy, not props): https://base-ui.com/react/components/popover.md
 
+## Prose
+- category: Layout, status: experimental
+Flow container that spaces long-form text and the blocks inside it. Also called an article or rich-text container. Use Stack or Row for UI layout.
+- props: node_modules/@imfusion/web-ui/src/docgen/doc.gen.json -> .prose (jq: jq '.prose' node_modules/@imfusion/web-ui/src/docgen/doc.gen.json)
+
 ## Row
 - category: Layout, status: stable
 Horizontal layout primitive for spacing, aligning, and wrapping children. Also called a horizontal stack or flex row.

package/src/llms/skills/imf-web-ui-conventions/SKILL.md

@@ -17,7 +17,7 @@ a gap or to make a deliberate deviation visible; do not refactor a project just
 | Topic                                            | Read when                                                       |
 | ------------------------------------------------ | --------------------------------------------------------------- |
 | [library-setup](topics/library-setup.md)         | Installing or repairing stylesheet and provider wiring.         |
-| [library-boundary](topics/library-boundary.md)   | Rendering Web UI components, wrapping them, or choosing a peer. |
+| [library-boundary](topics/library-boundary.md)   | Rendering, locking, or wrapping components, or choosing a peer. |
 | [authentication](topics/authentication.md)       | Protecting routes or defining login and logout.                 |
 | [react](topics/react.md)                         | Designing component roles, state ownership, or effects.         |
 | [components](topics/components.md)               | Adding files or deciding component anatomy.                     |

package/src/llms/skills/imf-web-ui-conventions/templates/AUDIT_CHECKLIST.md

@@ -13,6 +13,7 @@ sections one to one — change a topic's sections and this file follows in the s
 
 - [ ] Stay behind the library
 - [ ] Wrap primitives when the app has a reason to
+- [ ] Lock a field: read-only or disabled
 - [ ] Derive types, don't import them
 - [ ] Integrations own their peers
 - [ ] Styling crosses the boundary through seams
@@ -56,6 +57,7 @@ sections one to one — change a topic's sections and this file follows in the s
 - [ ] CSS authoring
 - [ ] Build custom UI from tokens
 - [ ] Override through the sanctioned seams
+- [ ] Spacing
 - [ ] The color system
 - [ ] Browser floor
 - [ ] Responsive styling
@@ -101,10 +103,9 @@ sections one to one — change a topic's sections and this file follows in the s
 - [ ] Devtools
 - [ ] Docs over memory
 - [ ] Prettier
-- [ ] ESLint
-- [ ] tsconfig
-- [ ] Staged files
-- [ ] CSS class names
+- [ ] ESLint and TypeScript
+- [ ] Pre-commit checks
+- [ ] Vite plugins
 
 ## npm project — `npm-project`
 

package/src/llms/skills/imf-web-ui-conventions/topics/library-boundary.md

@@ -28,6 +28,19 @@ Module classes.
 An `experimental` primitive should be wrapped once before it is used throughout an app. That gives an API change one place to
 land.
 
+## Lock a field: read-only or disabled
+
+Ask whether the value is final here or the control is unavailable right now.
+
+- `readOnly`: the value is real data the user cannot change in this context, such as an invited email or a generated ID. It
+  stays focusable, selectable, and copyable, screen readers announce it as read only, and the form submits it.
+- `disabled`: the control does not apply until something on this screen changes, such as a field that waits for another
+  choice or a form that is saving. It leaves the tab order and the form data. Show the reason next to it.
+- Plain text: nothing in the view is ever editable. Render a label and the value instead of a locked input.
+
+Set one of the two. When both apply, for example a read-only field inside a disabled `Fieldset`, disabled wins in behavior
+and in the library's styling. Re-derive a read-only value on the server instead of trusting the submitted copy.
+
 ## Derive types, don't copy them
 
 The library intentionally does not export component `Props` interfaces. Use `React.ComponentProps<typeof Component>` and

package/src/llms/skills/imf-web-ui-conventions/topics/react.md

@@ -9,7 +9,7 @@ looks.
   component CSS.
 - **Partials** are reusable compositions extracted because they read as a unit. They have light logic and no styling of their
   own.
-- **Layout components** arrange content with `Stack`, `Row`, grids, and token gaps.
+- **Layout components** arrange content with `Stack`, `Row`, grids, and token gaps, and wrap long-form text in `Prose`.
 - **Dumb components** receive data and callbacks, render UI, and own their styles. They do not fetch, route, or contain
   business rules.
 

package/src/llms/skills/imf-web-ui-conventions/topics/styling.md

@@ -50,6 +50,31 @@ hook, not a state flag.
 }
 ```
 
+## Spacing
+
+Web UI components have no outer margin. The parent sets the distance between its children: `Stack` and `Row` gaps in UI,
+`Prose` for long-form text. Inside a flex or grid gap a margin adds to the gap instead of collapsing, so do not add one to a
+Web UI component.
+
+```tsx
+// Wrong: the margin adds to the Stack gap.
+<Stack gap="3">
+  <Typo.P style={{ marginBlockEnd: "1em" }}>Your study is ready.</Typo.P>
+  <Callout.Root>…</Callout.Root>
+</Stack>
+
+// Right: UI spaced by the gap, text spaced by Prose.
+<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>
+```
+
 ## The color system
 
 Use surface roles (`main`, `support`, `minor`), the separate `brand` and `primary` roles, status roles, and the three accent

package/src/llms/skills/imf-web-ui-conventions/topics/tooling.md

@@ -88,3 +88,6 @@ export default defineConfig({
 `imfusionBrandAssets` serves the complete favicon set during development and emits it at stable root URLs during builds.
 Register `readableCssModuleNames` in every compiler that processes the app's CSS, including development, Storybook, and
 production. A compiler left out produces different class names and styles that appear to work only in some environments.
+
+`localWebUILink` dedupes the library's peer dependencies when `@imfusion/web-ui` is linked from a local checkout
+(`file:../web-ui`), so the app loads one React. It does nothing for an installed package and does not cover server rendering.

package/src/llms/skills/imf-web-ui-update/SKILL.md

@@ -108,7 +108,8 @@ This phase reads and reports: every file stays as it is until the person approve
 releases read, then report separately:
 
 - migrations: every `Breaking` entry and migration step, mapped to the call sites it affects here and the fix the changelog
-  shows; a step with no matching code is reported as not applicable;
+  shows; a step with no matching code is reported as not applicable. A style-only change, such as a removed margin, raises no
+  type error: find its call sites by component usage;
 - compatibility fixes required by changed imports or types that the changelog does not cover;
 - existing uses affected by a changed API or documented behavior;
 - suggestions: new features from the highlights and `Added` entries that fit what the project already builds, each with the

package/src/llms/skills/imf-web-ui-ux/SKILL.md

@@ -54,7 +54,8 @@ reason.
 ## Build the hierarchy
 
 - Frame an application with `AppShell`.
-- Compose `Stack` and `Row` for spacing and arrangement. Use `Separator` for a real division.
+- Compose `Stack` and `Row` for spacing and arrangement, and wrap long-form text in `Prose`. Use `Separator` for a real
+  division.
 - Use `Typo` for text hierarchy instead of styling raw headings beside it.
 - Give a view one primary action. Make other actions quieter.
 - Choose density from the user's frequency and data volume: frequent work and large data need compact layouts; occasional