npm - cortena-ui - Versions diffs - 1.12.0 → 1.13.0 - Mend

cortena-ui 1.12.0 → 1.13.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (16) hide show

package/CHANGELOG.md +85 -0
package/README.md +144 -6
package/dist/components/app-shell.d.ts +125 -2
package/dist/components/app-shell.js +471 -89
package/dist/components/app-shell.js.map +1 -1
package/dist/components/badge.d.ts +1 -1
package/dist/components/button.d.ts +1 -1
package/dist/components/dropdown-menu.js +21 -21
package/dist/components/dropdown-menu.js.map +1 -1
package/dist/core.d.ts +2 -2
package/dist/core.js +2 -2
package/dist/index.d.ts +2 -2
package/dist/index.js +2 -2
package/package.json +1 -1
package/src/components/app-shell.tsx +716 -38
package/src/entries/core.ts +2 -2

package/CHANGELOG.md CHANGED Viewed

@@ -3,6 +3,91 @@
 Notable changes per release. Versions before 1.6.0 are recorded in the git log
 and in `../../CONSUMING.md`; this file starts where the changelog does.
+## 1.13.0
+### Added
+- **`AppShell` has a navigation contract** (DESIGN-88). `nav` takes groups of
+  items — id, label, lucide icon or registered mark, href, badge, `exact` —
+  with an optional section label per group and a `footer` for the one thing in
+  a sidebar that is not navigation. Active state comes from `activeId`,
+  `isActive(href, item)` or `pathname`, in that order; cortena-ui still has no
+  router dependency, and `onNavigate` is where react-router takes over without
+  the `href` stopping being real. Below 1024px the sidebar becomes a menu
+  button and a drawer. `nav={null}` renders no sidebar, which is a legal state.
+  The five extensions in the shared-shell mockup would otherwise have shipped
+  five sidebars: five widths, five active treatments, five answers to badges
+  and groups.
+- **`headerSlot`**, between the extension name and the avatar, for a live
+  status pill, the org the screen is scoped to, or one secondary action —
+  and for nothing else. README, "The header slot and the avatar menu", has the
+  list of what may not go there.
+- **`menuItems`**, inserted between Settings and Log out in the avatar menu.
+  Log out stays last and stays behind its separator.
+- **`bottomInset`**, and `data-bottom-bar` detection when it is not given. The
+  theme/help cluster and anything in `agentSlot` lift clear of a mobile bottom
+  tab bar instead of covering two of its tabs. The shell publishes
+  `--ds-shell-bottom-inset` and `--ds-shell-header-height` on its own element
+  and on `<html>`, so a pop-up that portals out of the shell can read them.
+- **`HELP_PANEL_ID` and `NAV_DRAWER_ID`** are exported from `cortena-ui/core`
+  and the root barrel — the ids the shell gives the help region and the mobile
+  drawer, for a consumer that wires its own control's `aria-controls` to one
+  of them. They were exported from the module and reachable from neither entry.
+### Changed
+- **The help panel starts below the header.** It was `fixed top-6 right-6`,
+  which put it over the 64px header and over the avatar trigger it sits next
+  to. It now starts 12px below the header and still stops 12px above the
+  cluster (DESIGN-88).
+- **`BottomRightCluster` sets its own `bottom`.** It is now
+  `calc(24px + var(--ds-shell-bottom-inset, 0px))` as an inline style rather
+  than the `bottom-6` class, because the value is `calc()` over a variable the
+  consumer may not have set. **Migration:** an existing
+  `className="bottom-22 lg:bottom-6"` on the cluster no longer wins — an
+  inline style beats a utility class — and is now wrong twice over, since it
+  never moved the agent pop-up in `agentSlot`. Delete the override and give
+  the bottom bar `data-bottom-bar`, or pass `bottomInset`; both lift the
+  cluster and the pop-up together (DESIGN-88).
+- **The mobile drawer is a real modal.** It was `role="dialog"
+  aria-modal="true"` with no focus trap: focus stayed on the menu button,
+  Tab walked straight out into the shell under the scrim, and the page
+  scrolled behind it. Focus now starts on its close button, Tab and Shift+Tab
+  cycle inside it, the rest of the shell is `inert` while it is open, body
+  scroll is locked and restored, and focus returns to the menu button
+  (DESIGN-88 review).
+- **A modified click belongs to the browser.** `onNavigate` no longer fires —
+  and the drawer no longer closes — for a middle-click or a
+  cmd/ctrl/shift/alt-click, so "open in a new tab" works without every
+  consumer repeating the same guard before its `preventDefault()`. A router's
+  `onNavigate` written to the old contract keeps working; its own guard is
+  now redundant rather than required (DESIGN-88 review).
+- **`--ds-shell-header-height` is measured**, not restated. The constant is
+  declared once and the header takes it as its height; what lands on `<html>`
+  and on the shell element is the height the browser laid out.
+### Fixed
+- **More than one shell on a page no longer fights over `<html>`.** Every
+  shell wrote `--ds-shell-bottom-inset` and `--ds-shell-header-height` there
+  and every unmount removed them, so the values were whichever shell committed
+  last and the first to leave took them from the rest — visible in the token
+  guide, which mounts three. The first shell to mount owns the pair; the last
+  to unmount clears it (DESIGN-88 review).
+- **`aria-controls` no longer dangles.** The menu button and the help button
+  named an id that was on the page only while the drawer, or the panel, was
+  mounted; the attribute is now set only while it is (DESIGN-88 review).
+- **The shell's ResizeObservers survive a re-render.** The cluster's and the
+  bottom bar's effects listed `agentSlot`, `helpOpen` and `children` as
+  dependencies — fresh element objects every render — so both observers were
+  torn down and rebuilt on every render of the page underneath. They are keyed
+  on the DOM node now (DESIGN-88 review).
+- **`BrandMark` no longer logs three React errors per page.**
+  `safeRootAttributes` spread a mark's root attributes into JSX in their SVG
+  spelling — `stroke-width`, `stroke-linecap`, `stroke-linejoin` — and React
+  19 warned about each on every screen of every extension. They are camelCased
+  on the way in; the values still reach the DOM unchanged (DESIGN-88).
 ## 1.12.0
 ### Changed

package/README.md CHANGED Viewed

@@ -124,7 +124,7 @@ regression; `test/chart-bundle.test.tsx` says which line caused it.
 - **Tested in a real browser.** Tests assert computed pixels against the
   token the browser resolved. A dangling `var()` paints transparent, which the
   tests catch and jsdom cannot. Most tests pin a theme and run once; see
-  "Which tests run in both themes".
+  "Which tests run where".
 - **Every component appears in the guide.** `guide/sections.tsx` is the visual
   check in light, dark and system-dark; add an entry with every variant and
   size when adding a component.
@@ -136,7 +136,10 @@ how-to-create-a-cortena-extension, audit rule P-10): the registered brand mark
 and the extension name top left, the avatar menu — the only settings entry
 point — top right, and one fixed bottom-right cluster holding the theme toggle
 then the help button. `BrandMark`, `BottomRightCluster`, `ThemeToggle`,
-`HelpButton` and `documentTitle` are exported alongside it.
+`HelpButton` and `documentTitle` are exported alongside it, and so are
+`HELP_PANEL_ID` and `NAV_DRAWER_ID` — the ids the shell gives the help region
+and the mobile drawer, for a consumer wiring its own `aria-controls` to one of
+them.
 The mark comes from `cortena-design/marks` by `extension.id`, which is the same
 file the Apps tile, the MCP app card, the agent pop-up pill and the favicon
@@ -147,6 +150,107 @@ favicon".
 `helpPanel` is a slot until `HelpPanel` lands (EXTBP-24); `help.source` is the
 functional document the panel will read.
+### Navigation
+`nav` is the left sidebar, and it is the shell's so that five extensions do not
+invent five of them (DESIGN-88):
+```tsx
+<AppShell
+  extension={{ id: "tasks", name: "Tasks" }}
+  user={user}
+  nav={{
+    pathname,                       // from the router; see below
+    groups: [
+      { items: [{ id: "dashboard", label: "Dashboard", icon: LayoutDashboard, href: "/", exact: true }] },
+      {
+        label: "Projects",          // a labelled section
+        items: [
+          { id: "all", label: "All Projects", icon: FolderKanban, href: "/projects", exact: true },
+          { id: "alerts", label: "Alerts", icon: Bell, href: "/alerts", badge: 9 },
+        ],
+      },
+    ],
+    footer: <StorageMeter />,       // the one thing that is not navigation
+  }}
+/>
+```
+- **`icon`** is a lucide component or the id of a mark registered in
+  `cortena-design/marks`.
+- **`badge`** is a count or a short string, painted from tokens. `0` and `""`
+  draw nothing — an empty chip is worse than no chip.
+- **Active state** comes from one of three, in this order: `activeId` (the
+  item's id), `isActive(href, item)` (a callback), or `pathname` (compared to
+  each `href` as a prefix, or exactly for an item marked `exact`). Give none
+  and nothing is active: cortena-ui has no router dependency, and reading
+  `window.location` here would be right on first paint and stale after every
+  navigation.
+- **react-router** passes `pathname: useLocation().pathname` and keeps
+  navigation client-side with `onNavigate`, which is called before the browser
+  follows the real `href`:
+  ```tsx
+  onNavigate: (item, event) => {
+    event.preventDefault();
+    navigate(item.href);
+  },
+  ```
+  The `href` stays real either way, so middle-click, "open in new tab" and
+  copy-link all still work: the shell does not call `onNavigate` at all for a
+  middle-click or a cmd/ctrl/shift/alt-click, so that guard does not belong in
+  every consumer.
+- **`href` is compared as a plain path.** A value carrying a query or a hash
+  (`/reports?tab=open`, `/docs#intro`) does not prefix-match the pathname and
+  will never light up. Give the item its base path and resolve `activeId`
+  yourself.
+- **Below 1024px** the sidebar becomes a menu button in the header and a
+  drawer, closed by Escape, by the scrim, or by following an item. It is a
+  real modal: focus moves to its close button, Tab cycles inside it, the rest
+  of the shell is `inert` while it is open, the page under it does not scroll,
+  and focus returns to the menu button on close.
+- **`nav={null}`** renders no sidebar and no menu button. That is a legal
+  state, and the right one for an extension whose whole navigation lives
+  inside one page.
+### The header slot and the avatar menu
+`headerSlot` sits between the extension name and the avatar; `menuItems` are
+inserted between Settings and Log out. Both exist because the top bar was
+closed and three extensions had something real to put in it — and both stay
+narrow on purpose (§10):
+| May go in `headerSlot` | May not |
+| --- | --- |
+| Live status about what is on screen — Assure's "Claude executing" pill | Navigation of any kind. That is `nav`, or it is in the page |
+| The org, workspace or tenant the screen is scoped to — Tasks' "Cortena Labs" | The theme control. It is in the bottom-right cluster, once |
+| **One** secondary action, text or icon, that belongs to the whole extension rather than to the page — Report an issue | Help. It is the help button, and its panel |
+| | Settings, or anything that opens settings. The avatar menu is the only entry point |
+| | A page-level action. Those are `PageHeader`'s `actions` |
+`menuItems` takes destinations that are the user's rather than the screen's —
+Assure's Permissions, a Report-issue dialog. Log out stays last and stays
+behind its separator: an extension item cannot push itself under the
+destructive action.
+### The bottom inset, and the two variables the shell publishes
+`AppShell` sets `--ds-shell-header-height` and `--ds-shell-bottom-inset`, on
+its own element and on `<html>`, so anything that portals out of the shell can
+still tell where the chrome is. `<html>` has one pair of them and a page may
+hold more than one shell — the token guide holds three — so the first shell to
+mount owns the pair and the last to unmount clears it; every shell publishes
+its own values on its own element regardless.
+An extension with a bottom tab bar gives that bar `data-bottom-bar` and the
+shell measures it — the measurement is 0 while the bar is hidden, so a
+`lg:hidden` tab bar lifts the cluster on a phone and nowhere else. `bottomInset`
+(a number of pixels, or any CSS length) sets the same distance by hand. Both
+move the theme/help cluster **and** whatever `agentSlot` renders, which is what
+the old per-extension `className="bottom-22 lg:bottom-6"` workaround could not
+do.
 ## The agent pop-up
 `AgentChatPopup` is the extension's own Cortena Agent, in the corner of every
@@ -697,11 +801,12 @@ action is shaped like A2UI's client-to-server `action`, and the catalogue is a
 schema-per-component registry. Swapping the engine later is mechanical. Nothing
 from `@a2ui/*` is installed, so `vitest.config.ts` has no entry for it.
-## Which tests run in both themes
+## Which tests run where
-`vitest.config.ts` has two projects. **`light`** runs every file once in a
-Chromium whose OS colour scheme is light; **`dark`** runs a second time, in a
-dark Chromium, only the files whose name ends `.theme.test.tsx`. Tag a test with
+`vitest.config.ts` has four projects. **`light-1`, `light-2` and `light-3`**
+between them run every file once, in a Chromium whose OS colour scheme is
+light; **`dark`** runs a second time, in a dark Chromium, only the files whose
+name ends `.theme.test.tsx`. Tag a test with
 that suffix when its result depends on the browser's own colour scheme — that
 is, when it asserts a theme-dependent value while no `data-theme` attribute is
 set, the `@media (prefers-color-scheme: dark)` branch of `tokens.css`. Nothing
@@ -713,6 +818,38 @@ test in a file needs the tag, move that test to a sibling `*.theme.test.tsx`
 rather than paying for the whole file twice — six such files exist today, and
 `pnpm test:dark` runs exactly them.
+The three `light` projects are a wall-clock split, not a behaviour split
+(DESIGN-86). Files run one at a time inside a project — parallel files made
+overlay tests time out and let one file's pointer position leak into the next —
+so 72 light files in one project meant 72 browser-page setups end to end, and
+that, not the test work, was the suite's wall time. Vitest runs *projects* side
+by side, so splitting the light files three ways makes the wall time the slowest
+shard rather than the sum. Nothing about isolation changes: each shard is still
+serial inside itself, and three light shards plus `dark` is four Chromium
+contexts at once, the same kind of concurrency the suite has always had and as
+many as an 8 GB laptop takes without swapping.
+Measured on the machine this was written on: the full suite went from
+**78.3 s** to **54.3 s** wall for the same 78 file runs and 812 tests, while
+CPU time rose from 73 s to 95 s. It is a third off, not the two-thirds the file
+counts suggest, and the gap is the fixed cost each project pays for itself — a
+Vite server, the `optimizeDeps` pre-bundle above, and a browser launch, worth
+roughly ten seconds before the first file runs — plus what four of those
+contending for 8 GB costs the ones already running. Splitting further buys less
+each time and costs memory sooner; measure before raising `LIGHT_SHARDS`.
+A file's shard is `hash(path) % 3`, an FNV-1a of its path — deliberately not an
+alphabetical split. Alphabetically, adding one file shifts every file after it
+across a boundary, so shard membership churns on every new test; hashing the
+path leaves every existing file where it was and puts only the new file
+somewhere, and a file moves only when it is renamed. The spread stays close to
+even on its own (21/27/24 over today's 72 files). You never choose a shard, and
+nothing you write needs to know which one it is in: `pnpm test` selects changed
+files across all of them, and a shard with nothing changed in it simply runs
+nothing. If the shards ever drift badly out of balance, raise `LIGHT_SHARDS` in
+`vitest.config.ts` — but keep the light shards plus `dark` at four contexts or
+fewer unless the machine has more memory.
 ## Commands
 ```bash
@@ -743,6 +880,7 @@ src/styles/index.css  what consumers import after the tokens: animation
                       utilities and the Base UI data-attribute variants
 scripts/bundle-probe.mjs  builds a consumer app per entry and weighs it
 test/                 browser tests; setup.css is the consumer recipe verbatim
+                      split by path hash across three concurrent light projects
                       *.theme.test.tsx also run in a dark Chromium
                       *.test.mjs are the Node-side bundle budgets
 guide/                Vite app: ?theme=light|dark|system frames, or all three

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

@@ -1,4 +1,5 @@
 "use client";
+import { LucideIcon } from "lucide-react";
 import * as React from "react";
 //#region src/components/app-shell.d.ts
 /**
@@ -54,8 +55,15 @@ export interface BottomRightClusterProps extends React.ComponentProps<"div"> {
  * The one fixed container in the bottom-right corner. It exists so that no
  * extension positions a floating control itself — that is how a third one
  * appears and covers one of the first two.
+ *
+ * Its distance from the bottom edge is 24px PLUS `--ds-shell-bottom-inset`,
+ * which `AppShell` sets from its `bottomInset` prop or from a `data-bottom-bar`
+ * element it finds in the page. On a phone with a bottom tab bar the cluster
+ * used to sit on top of two of the tabs; Tasks worked around it with
+ * `className="bottom-22 lg:bottom-6"` on its own cluster, which the agent
+ * pop-up inside `agentSlot` had no equivalent of (DESIGN-88).
  */
-declare function BottomRightCluster({ className, agentSlot, children, ...props }: BottomRightClusterProps): React.JSX.Element;
+declare function BottomRightCluster({ className, style, agentSlot, children, ...props }: BottomRightClusterProps): React.JSX.Element;
 export interface ThemeToggleProps extends Omit<React.ComponentProps<"button">, "onClick"> {
   /** localStorage key, forwarded to `useCortenaTheme`. */
   storageKey?: string;
@@ -66,12 +74,90 @@ export interface ThemeToggleProps extends Omit<React.ComponentProps<"button">, "
  * a one-tap decision, not a settings visit.
  */
 declare function ThemeToggle({ className, storageKey, ...props }: ThemeToggleProps): React.JSX.Element;
+/** The id the shell gives its help region, and the button's `aria-controls`. */
+export declare const HELP_PANEL_ID = "cortena-help-panel";
+/** The id the shell gives its mobile nav drawer, and the menu button's `aria-controls`. */
+export declare const NAV_DRAWER_ID = "cortena-nav-drawer";
 export interface HelpButtonProps extends React.ComponentProps<"button"> {
   /** Whether the panel it controls is open. */
   open?: boolean;
 }
 /** The help affordance. Right of the theme toggle, always — order is fixed (§9.3). */
 declare function HelpButton({ className, open, ...props }: HelpButtonProps): React.JSX.Element;
+/**
+ * A nav item's glyph: a lucide icon component, or the id of a mark registered
+ * in `cortena-design/marks` (so a nav row can wear another extension's mark
+ * without importing its SVG).
+ */
+export type AppShellNavIcon = LucideIcon | string;
+export interface AppShellNavItem {
+  /** Stable id. What `activeId` names, and what `data-nav-item` carries. */
+  id: string;
+  label: string;
+  icon?: AppShellNavIcon;
+  /** The destination. Rendered as a real `href`, so middle-click and copy-link work. */
+  href: string;
+  /** A count or a short word. Rendered from tokens; `0` and `""` draw nothing. */
+  badge?: number | string;
+  /** Match `pathname` exactly rather than as a prefix. Ignored under `activeId`/`isActive`. */
+  exact?: boolean;
+}
+export interface AppShellNavGroup {
+  /** Section heading. A group with no label is separated by a rule instead. */
+  label?: string;
+  items: AppShellNavItem[];
+}
+export interface AppShellNav {
+  groups: AppShellNavGroup[];
+  /**
+   * Which item is active, decided in one of three ways, in this order:
+   *
+   *   `activeId`   the item's own id. The simplest, and the only one that
+   *                needs nothing from the router.
+   *   `isActive`   a callback per item. Use it when "active" is not a path
+   *                comparison — a query parameter, a nested layout route.
+   *   `pathname`   the current path, compared to each `href`: a prefix match,
+   *                or an exact one for an item marked `exact`.
+   *
+   * cortena-ui has no router dependency and never will, so one of the three
+   * has to come from the consumer. With react-router:
+   *
+   * ```tsx
+   * const { pathname } = useLocation();
+   * const navigate = useNavigate();
+   *
+   * <AppShell
+   *   nav={{
+   *     groups,
+   *     pathname,
+   *     // Keep it a client-side navigation; the href stays real for
+   *     // middle-click, "open in new tab" and copy-link, and the shell never
+   *     // calls this for a modified or middle click.
+   *     onNavigate: (item, event) => {
+   *       event.preventDefault();
+   *       navigate(item.href);
+   *     },
+   *   }}
+   * />
+   * ```
+   *
+   * Give none of the three and nothing is active — deliberately, because the
+   * alternative is reading `window.location` here, which would be right on
+   * first paint and then silently stale on every navigation after it.
+   */
+  activeId?: string;
+  isActive?: (href: string, item: AppShellNavItem) => boolean;
+  pathname?: string;
+  /** Intercept a click. Called before the browser follows the `href`. */
+  onNavigate?: (item: AppShellNavItem, event: React.MouseEvent<HTMLAnchorElement>) => void;
+  /**
+   * Pinned under the items: File Vault's storage meter, Flux's stream status.
+   * The one thing in the sidebar that is neither navigation nor chrome.
+   */
+  footer?: React.ReactNode;
+  /** The landmark's accessible name. Default "Sections". */
+  label?: string;
+}
 export interface AppShellExtension {
   /** Registered mark id, from `x-cortena.icon` in the OpenAPI document. */
   id: string;
@@ -95,9 +181,46 @@ export interface HelpPanelSlotProps {
   source?: string;
   onClose: () => void;
 }
+export interface AppShellMenuItem {
+  id: string;
+  label: string;
+  icon?: LucideIcon;
+  onSelect: () => void;
+}
 export interface AppShellProps extends Omit<React.ComponentProps<"div">, "title"> {
   extension: AppShellExtension;
   user: AppShellUser;
+  /**
+   * The left sidebar. `null` (or omitted) renders no sidebar and no menu
+   * button — a legal state, and the right one for an extension whose whole
+   * navigation is inside one page.
+   */
+  nav?: AppShellNav | null;
+  /**
+   * Between the extension name and the avatar. For state, not for controls:
+   * a live-status pill, the org or workspace the screen is scoped to, or one
+   * secondary action. Navigation, theme, help and settings do NOT go here —
+   * they have exactly one home each and a second one is how two extensions
+   * stop looking like one product (§10).
+   */
+  headerSlot?: React.ReactNode;
+  /**
+   * Extra avatar-menu items, inserted between Settings and Log out. For a
+   * destination that is the user's, not the screen's — Assure's Permissions,
+   * a Report-issue dialog. Not a second way to reach something already in the
+   * shell.
+   */
+  menuItems?: AppShellMenuItem[];
+  /**
+   * How far the bottom-right cluster (and anything in `agentSlot`) lifts off
+   * the bottom edge, on top of its own 24px. A number is pixels.
+   *
+   * Omit it and the shell measures the first `[data-bottom-bar]` element
+   * inside itself instead, which is 0 when that element is hidden — so a
+   * `lg:hidden` mobile tab bar lifts the cluster on a phone and nowhere else,
+   * with nothing to keep in sync.
+   */
+  bottomInset?: string | number;
   /** Opens the extension's own settings route. The avatar menu is the only way in. */
   onSettings?: () => void;
   onProfile?: () => void;
@@ -114,7 +237,7 @@ export interface AppShellProps extends Omit<React.ComponentProps<"div">, "title"
   /** localStorage key for the theme choice, forwarded to `useCortenaTheme`. */
   themeStorageKey?: string;
 }
-declare function AppShell({ className, extension, user, onSettings, onProfile, onLogout, help, helpPanel, agentSlot, themeStorageKey, children, ...props }: AppShellProps): React.JSX.Element;
+declare function AppShell({ className, style, extension, user, nav, headerSlot, menuItems, bottomInset, onSettings, onProfile, onLogout, help, helpPanel, agentSlot, themeStorageKey, children, ...props }: AppShellProps): React.JSX.Element;
 /**
  * `<title>` for an extension: the extension first, because that is what
  * distinguishes one tab from another, and the product second so a row of tabs