@imfusion/web-ui 0.10.1-dev.37.g9147f90f → 0.10.1-dev.41.g467e0e1a

package/CHANGELOG.md

@@ -36,7 +36,6 @@ never changes the character width, so columns stay aligned. CoFo Sans Mono still
   - The aside drawer pads its content inside the scroll area; a `padding` on `AppShell.Aside` in drawer mode adds to it.
 - **Breaking:** The AppShell navbar drawer opens from the inline start instead of the inline end. — Nikolaus Brunner <brunner@imfusion.com>
   - Consumer CSS that places something against the navbar drawer's right edge moves to its left edge.
-- **Breaking:** The AppShell navbar drawer renders its own close on the logo row. Remove the close `AppShell.Burger` your navbar's first section renders, or the drawer shows two closes. — Nikolaus Brunner <brunner@imfusion.com>
 - **Breaking:** `AppShell.Navbar` renders its own logo row and account foot, and stacks its children as nav items with its own spacing. [AppShell](src/components/app-shell/app-shell.mdx) — Nikolaus Brunner <brunner@imfusion.com>
   - Pass the brand as `logo` and the account card as `account`, and drop the `AppShell.Section`s that held them. Omit `logo` to use the default ImFusion logo; `logo={null}` leaves the row empty.
 - **Breaking:** The current `AppShell.NavItem` has no background surface; its label is underlined and the other items are dimmed. [AppShell](src/components/app-shell/app-shell.mdx) — Nikolaus Brunner <brunner@imfusion.com>
@@ -52,9 +51,27 @@ never changes the character width, so columns stay aligned. CoFo Sans Mono still
   - An account switcher built on `AccountCard.Group` has no replacement yet; keep the old version until one ships.
 - **Breaking:** An `AccountCard` in the `AppShell.Navbar` foot lines up with the nav items and no longer takes the 8px inset. — Nikolaus Brunner <brunner@imfusion.com>
   - Pass the card as `account`; a card kept in a Section keeps its own padding.
+- **Breaking:** The shell renders the mobile bar itself: the navbar's logo and the toggle for its drawer. [AppShell](src/components/app-shell/app-shell.mdx) — Nikolaus Brunner <brunner@imfusion.com>
+  - Remove `AppShell.Burger` and a logo of your own from your `AppShell.Header`; the Burger is no longer exported, and phones would show two logos.
+- **Breaking:** The header takes the navbar's `variant`: beside a `branded` navbar it fills with the primary color and its text is on-color. [AppShell](src/components/app-shell/app-shell.mdx) — Nikolaus Brunner <brunner@imfusion.com>
+  - Remove a header color set to match the branded navbar. A custom surface still goes in `--imf-ui-appshell-header-bg`, which is unset by default and falls back to the navbar variant's surface.
+- **Breaking:** `AppShell.Header` is a flex row, and it wraps its children in a container that aligns them to the inline end. [AppShell](src/components/app-shell/app-shell.mdx) — Nikolaus Brunner <brunner@imfusion.com>
+  - Give your own row `width: 100%` to span the header.
 
 ### Added
 
+- `npx web-ui link <checkout>` copies a local checkout's build into the app's `node_modules/@imfusion/web-ui` and syncs it
+  after each rebuild. `npx web-ui unlink` restores the published files byte for byte. — Nikolaus Brunner <brunner@imfusion.com>
+  - `localWebUILink` serves a linked build without pre-bundling it and reloads the page on each sync. `imf-web-ui-setup` proposes registering it, and `imf-web-ui-audit` reports a `vite.config.ts` without it as Missing.
+  - Migrating from `"@imfusion/web-ui": "file:../web-ui"`: set the dependency back to the registry version, run `npm install`,
+    then run `npx web-ui link ../web-ui`.
+- The shell's navigation toggle sets `aria-controls` from the navbar, and reads the `id` the navbar generates. A consumer `id` on the Navbar is what it points at. — Nikolaus Brunner <brunner@imfusion.com>
+- [`useDisclosure`](src/hooks/use-disclosure.stories.tsx#UseDisclosure) keeps an open state that works controlled or uncontrolled, and returns `open`, `setOpen`, and `toggle`. — Nikolaus Brunner <brunner@imfusion.com>
+- `AppShell.Navbar` and `AppShell.Aside` take `defaultOpen` and keep their own open state when `open` is omitted, and close an uncontrolled drawer when they dock. A controlled `open` is never changed by docking. — Nikolaus Brunner <brunner@imfusion.com>
+- An `AppShell.Aside` opens from the consumer's state, such as a row selection, through `open` and `onOpenChange`. — Nikolaus Brunner <brunner@imfusion.com>
+- `AppShell.Main` content is a flex column at least as tall as Main, so a child with `flex: 1` fills the rest. — Nikolaus Brunner <brunner@imfusion.com>
+- `AppShell.Aside` content wraps long words such as emails and IDs inside a narrow panel, in the docked aside and the drawer. — Nikolaus Brunner <brunner@imfusion.com>
+- An `AppShell.NavItem` followed inside the navbar drawer closes it, unless its `onClick` calls `event.preventDefault()`. — Nikolaus Brunner <brunner@imfusion.com>
 - [`ColorSchemeToggle`](src/components/color-scheme-toggle/color-scheme-toggle.mdx) lets the user pick Light, System, or
   Dark. It stores the choice through `useColorScheme` and needs no props; `label`, `lightLabel`, `systemLabel`, and
   `darkLabel` replace the English text — Nikolaus Brunner <brunner@imfusion.com>
@@ -85,13 +102,14 @@ never changes the character width, so columns stay aligned. CoFo Sans Mono still
 - `AppShell.Navbar` takes `logo` and `account`; the logo defaults to the ImFusion logo and lines up with the baseline of Main's first heading. [AppShell](src/components/app-shell/app-shell.mdx) — Nikolaus Brunner <brunner@imfusion.com>
 - `--imf-ui-appshell-heading-*`, `--imf-ui-appshell-navitem-dim`, `--imf-ui-appshell-navitem-underline-thickness`, and `--imf-ui-appshell-navitem-underline-offset` tune the logo row's strut and the NavItem underline. [AppShell](src/components/app-shell/app-shell.mdx) — Nikolaus Brunner <brunner@imfusion.com>
 - `AppShell.Aside` shows a close button in its drawer below `lg`, labelled by `closeLabel` (`Close panel` by default). [AppShell](src/components/app-shell/app-shell.mdx) — Nikolaus Brunner <brunner@imfusion.com>
-- `AppShell.Burger` with no props opens and closes the navbar drawer, so the header needs no state wiring. [AppShell](src/components/app-shell/app-shell.mdx) — Nikolaus Brunner <brunner@imfusion.com>
 - `Select.Root` takes a `width` of `auto`, `wide`, or `full`: `auto` keeps the 10rem trigger minimum, `wide` raises it to
   15rem, and `full` fills the parent. `--imf-ui-select-trigger-min-width` on `Select.Root` sets the minimum from CSS.
   [Select](src/components/select/select.mdx) — Nikolaus Brunner <brunner@imfusion.com>
 
 ### Changed
 
+- [`AppShell.Header`](src/components/app-shell/app-shell.mdx) is a page row that shows at every width, below the shell's bar on mobile. — Nikolaus Brunner <brunner@imfusion.com>
+  - The header pads its inline sides with `--imf-ui-appshell-padding`, so its content lines up with Main's.
 - AppShell — Nikolaus Brunner <brunner@imfusion.com>
   - The navbar rail, `AppShell.Main`, and the aside share `--imf-ui-appshell-padding` as their inline gutter, so their text lines up with no consumer CSS. [Docs](src/components/app-shell/app-shell.mdx)
   - `--imf-ui-appshell-navbar-padding` defaults to `--imf-ui-appshell-padding`, and `--imf-ui-appshell-aside-padding` defaults to `--imf-ui-appshell-padding`. Both stay overridable.
@@ -131,6 +149,7 @@ never changes the character width, so columns stay aligned. CoFo Sans Mono still
 
 ### Fixed
 
+- `Drawer.Popup` draws no focus ring around the whole panel when it takes focus on open; the controls inside keep theirs. — Nikolaus Brunner <brunner@imfusion.com>
 - `Chip` stays on one line within its container's width and ends in an ellipsis when the label doesn't fit. [Chip](src/components/chip/chip.mdx) — Nikolaus Brunner <brunner@imfusion.com>
 - Only the navbar drawer's own close shows while it is open; the header burger steps back until the drawer closes — Nikolaus Brunner <brunner@imfusion.com>
 - `Skeleton.Root` fades only its own content in when loading ends; the rest of the page stays still, and no `AbortError` reaches the console — Nikolaus Brunner <brunner@imfusion.com>

package/README.md

@@ -103,18 +103,27 @@ The main development skills are:
 
 ### 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:
+Keep this checkout's watch build running, then link it into the app:
 
-```json
-"@imfusion/web-ui": "file:../web-ui"
+```sh
+npm run dev:lib                  # here: rebuilds dist/ on every change
+npx web-ui link ../web-ui        # in the app: syncs dist/ into node_modules on every rebuild
 ```
 
-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.
+`link` takes the checkout path, or reads `WEB_UI_CHECKOUT` when the path is omitted. It copies the build into the app's
+`node_modules/@imfusion/web-ui`, keeps the published `dist/` and `package.json` in `node_modules/.web-ui-link/backup`, and
+writes a marker file, `.local-link.json`, into the package folder. It stays in the foreground and syncs after each rebuild.
+Ctrl+C stops syncing, and the app keeps the last synced build. Restart the app's dev server after `link` and after `unlink`,
+because the Vite config reads the link when the server starts.
+
+`npx web-ui unlink` restores the published files, removes the marker and the backup, and prints each step. Run it again and
+it reports that nothing is linked.
+
+The app's `package.json` and lockfile are never touched. `npm install` replaces the linked copy with the published package,
+so run `link` again after 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:
+The app registers `localWebUILink` in its Vite config and keeps it there. With no link it does nothing. With a link it serves
+the copied build without pre-bundling it and reloads the page on each sync:
 
 ```ts
 import { localWebUILink } from "@imfusion/web-ui/vite";
@@ -124,11 +133,5 @@ export default defineConfig({
 });
 ```
 
-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.
+Server rendering, including React Router prerendering, is not covered, and Base UI's CommonJS `use-sync-external-store`
+dependency can still fail there.

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

@@ -1,20 +1,46 @@
-import { Button as ButtonPrimitive } from '@base-ui/react/button';
 import { useRender } from '@base-ui/react/use-render';
 import { VariantProps } from 'class-variance-authority';
 declare const navbarSurface: (props?: ({
     variant?: "default" | "branded" | null | undefined;
 } & import('class-variance-authority/types').ClassProp) | undefined) => string;
-declare function Root({ ref, ...props }: React.ComponentProps<"div">): import("react/jsx-runtime").JSX.Element;
+/**
+ * AppShell — application layout shell.
+ *
+ * The classic dashboard frame: collapsible navbar/aside sidebars, a page
+ * header, an optional footer, and a scrolling main content area. Also called
+ * an app layout, application frame, dashboard shell, or sidebar layout.
+ *
+ * Composed of eight sub-components used with dot-notation: `AppShell.Root` wraps
+ * `AppShell.Header`, `AppShell.Navbar`, `AppShell.Aside`, `AppShell.Footer`,
+ * `AppShell.Main`, and (inside a sidebar) `AppShell.Section` and `AppShell.NavItem`.
+ *
+ * Sizing is CSS-driven — override the `--imf-ui-appshell-*` custom properties
+ * rather than passing dimension props. Below the responsive breakpoints the
+ * navbar (`md`) and aside (`lg`) open as drawers, and the shell renders the
+ * navbar's toggle itself.
+ *
+ * Copied and adapted from Mantine's AppShell; no upstream runtime dependency.
+ * MIT licensed (see Mantine repo).
+ *
+ * @see https://mantine.dev/llms/core-app-shell.md
+ */
+declare function Root({ ref, children, ...props }: React.ComponentProps<"div">): import("react/jsx-runtime").JSX.Element;
 declare namespace Root {
     var displayName: string;
 }
-declare function Header(props: React.ComponentProps<"header">): import("react/jsx-runtime").JSX.Element;
+/**
+ * AppShell.Header — the page row: a title and actions at every width. Below `md` it sits under the shell's bar, and from
+ * `md` it sits beside the rail.
+ */
+declare function Header({ className, children, ...props }: React.ComponentProps<"header">): import("react/jsx-runtime").JSX.Element;
 declare namespace Header {
     var displayName: string;
 }
 type DrawerProps = {
     /** Whether the drawer is open below the breakpoint. Ignored while the section is docked. */
     open?: boolean;
+    /** Whether the drawer starts open when `open` is omitted. */
+    defaultOpen?: boolean;
     /** Called when the drawer asks to open or close: scrim, swipe, or Escape. */
     onOpenChange?: (open: boolean) => void;
 };
@@ -30,7 +56,7 @@ type NavbarProps = React.ComponentProps<"nav"> & VariantProps<typeof navbarSurfa
  * color; children opt into on-color themselves. Below `md` the navbar opens as a drawer from the inline start, with its
  * close on the logo row.
  */
-declare function Navbar({ variant, open, onOpenChange, logo, account, children, ...props }: NavbarProps): import("react/jsx-runtime").JSX.Element;
+declare function Navbar({ variant, open, defaultOpen, onOpenChange, logo, account, children, id, ...props }: NavbarProps): import("react/jsx-runtime").JSX.Element;
 declare namespace Navbar {
     var displayName: string;
 }
@@ -45,7 +71,7 @@ type AsideProps = React.ComponentProps<"aside"> & DrawerProps & {
     closeLabel?: string;
 };
 /** Below `lg` the aside opens as a drawer: from the bottom on phones, from the inline end on tablets. */
-declare function Aside({ open, onOpenChange, resizable, onWidthChange, resizeLabel, closeLabel, children, ...props }: AsideProps): import("react/jsx-runtime").JSX.Element;
+declare function Aside({ open, defaultOpen, onOpenChange, resizable, onWidthChange, resizeLabel, closeLabel, children, ...props }: AsideProps): import("react/jsx-runtime").JSX.Element;
 declare namespace Aside {
     var displayName: string;
 }
@@ -65,21 +91,6 @@ declare function Section({ grow, ...props }: SectionProps): import("react/jsx-ru
 declare namespace Section {
     var displayName: string;
 }
-type BurgerProps = React.ComponentProps<typeof ButtonPrimitive> & {
-    /** Draws the cross and sets `aria-expanded`. Defaults to whether the navbar drawer is open. */
-    opened?: boolean;
-    /** Accessible name. Defaults to "Open navigation" or "Close navigation" from `opened`. */
-    label?: string;
-};
-/**
- * AppShell.Burger — the menu toggle: three sheared bands that cross while the navbar drawer is open. With no props it
- * opens and closes that drawer. Takes its color from the surface and hides from `md` up, where the navbar is docked, and
- * steps back while the drawer is open, so the drawer's own close is the only one shown.
- */
-declare function Burger({ opened, label, className, onClick, ...props }: BurgerProps): import("react/jsx-runtime").JSX.Element;
-declare namespace Burger {
-    var displayName: string;
-}
 type NavItemProps = useRender.ComponentProps<"a"> & {
     /** Leading icon, decorative. */
     icon?: React.ReactNode;
@@ -88,10 +99,11 @@ type NavItemProps = useRender.ComponentProps<"a"> & {
 };
 /**
  * AppShell.NavItem — a navbar link: icon, mono label, and an optional description. Takes its color from the navbar;
- * `aria-current="page"` underlines the label. Pass a router link through `render`.
+ * `aria-current="page"` underlines the label. Pass a router link through `render`. Followed inside the navbar drawer,
+ * it closes the drawer.
  */
-declare function NavItem({ icon, description, children, render, ...props }: NavItemProps): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
+declare function NavItem({ icon, description, children, render, onClick, ...props }: NavItemProps): import('react').ReactElement<unknown, string | import('react').JSXElementConstructor<any>>;
 declare namespace NavItem {
     var displayName: string;
 }
-export { Root, Header, Navbar, Aside, Footer, Main, Section, Burger, NavItem };
+export { Root, Header, Navbar, Aside, Footer, Main, Section, NavItem };

package/dist/hooks/index.d.ts

@@ -1,6 +1,8 @@
 export { useClipboard } from './use-clipboard';
 export type { UseClipboardOptions } from './use-clipboard';
 export { useColorScheme } from './use-color-scheme';
+export { useDisclosure } from './use-disclosure';
+export type { UseDisclosureOptions } from './use-disclosure';
 export { useMediaQuery } from './use-media-query';
 export type { UseMediaQueryOptions } from './use-media-query';
 export { useResizeObserver } from './use-resize-observer';

package/dist/hooks/use-disclosure.d.ts

@@ -0,0 +1,17 @@
+export interface UseDisclosureOptions {
+    /** The controlled open state. Leave it out to let the hook keep the state. */
+    open?: boolean;
+    /** The initial open state while uncontrolled. @default false */
+    defaultOpen?: boolean;
+    /** Called with the next state whenever it is requested, controlled or not. */
+    onOpenChange?: (open: boolean) => void;
+}
+/**
+ * Tracks an open/closed state that works controlled or uncontrolled, like a Base UI root. The hook updates its own
+ * state only while `open` is undefined, and always reports the request through `onOpenChange`.
+ */
+export declare function useDisclosure({ open, defaultOpen, onOpenChange }?: UseDisclosureOptions): {
+    open: boolean;
+    setOpen: (next: boolean) => void;
+    toggle: () => void;
+};

package/dist/index.d.ts

@@ -44,8 +44,8 @@ export { Tooltip, tooltipMeta } from './components/tooltip';
 export { Typo, typoMeta } from './components/typo';
 export { ImFusionLogo } from './components/logo';
 export { WebUIProvider } from './provider';
-export { useClipboard, useColorScheme, useMediaQuery } from './hooks';
-export type { UseClipboardOptions, UseMediaQueryOptions } from './hooks';
+export { useClipboard, useColorScheme, useDisclosure, useMediaQuery } from './hooks';
+export type { UseClipboardOptions, UseDisclosureOptions, UseMediaQueryOptions } from './hooks';
 export { cva, cx } from 'class-variance-authority';
 export { initialsFromEmail, splitEmail } from './utils/email';
 export { withBreakHints } from './utils/break-hints';