@namroodinc/liquid-editorial 0.1.5 → 0.1.7

package/AGENTS.md

@@ -4,6 +4,8 @@
 
 Add a decision document for every change going forward.
 
+Render button controls through the shared `Button` component, including controls inside other components and examples. Native button markup belongs only in `src/components/Button` (isolated test fixtures may use native controls). Use Button's standard variants, sizes, icons, focus, and disabled styling instead of copying them into a component stylesheet. Specialized widgets may retain their semantic layout, shared Field skin, or switch track/knob geometry.
+
 Every releasable change set must update the `Unreleased` section in `UPGRADING.md` with changes, adoption steps, compatibility notes, and verification steps for agents in consuming projects. Related edits share that section. Leave version increments to `.github/workflows/release.yml`: every push to `main` automatically bumps the patch version, versions the upgrade notes, validates, commits the release files, and publishes to npm. Keep the manifest and lockfile versions aligned and include this file and `UPGRADING.md` in the package.
 
 ## Using the installed package

package/README.md

@@ -1,6 +1,6 @@
 # Liquid Editorial
 
-Accessible React components for editorial products. The package ships ESM, CommonJS, TypeScript declarations, and explicit CSS entry points. It does not inject styles from JavaScript.
+Accessible React components for editorial products. The package ships ESM, CommonJS, TypeScript declarations, and explicit CSS entry points. Styles use those CSS entry points; the library does not inject styles through JavaScript.
 
 ## Install
 
@@ -35,6 +35,16 @@ Every family also has a direct entry point:
 import { Button } from "@namroodinc/liquid-editorial/components/Button";
 ```
 
+Use `Button` for action controls, including controls rendered inside other components. Its variants, sizes, icons, focus rings, and disabled states supply the shared appearance. Use `size="xs"` for compact actions inside a field or chip, such as clear and remove. For a custom square glyph, omit `iconStart` and provide visual children plus an accessible name:
+
+```tsx
+<Button variant="simple" isIconOnly aria-label="Account: Ada Lovelace">
+  <Avatar name="Ada Lovelace" size={32} aria-hidden="true" />
+</Button>
+```
+
+Pending Buttons replace custom glyphs with the shared spinner. Button-backed selects and date fields retain the shared Field skin; Switch retains its track and knob while composing Button.
+
 If an application only needs the design tokens, import `@namroodinc/liquid-editorial/tokens.css`. A small global normalization is available separately at `@namroodinc/liquid-editorial/reset.css`; it is never included automatically.
 
 ## Content models
@@ -43,7 +53,12 @@ If an application only needs the design tokens, import `@namroodinc/liquid-edito
 
 ```tsx
 import { useState } from "react";
-import { EntryEditor, validateEntryValues, type ContentModel, type EntryValues } from "@namroodinc/liquid-editorial";
+import {
+  EntryEditor,
+  validateEntryValues,
+  type ContentModel,
+  type EntryValues,
+} from "@namroodinc/liquid-editorial";
 
 const model: ContentModel = {
   fields: [
@@ -54,8 +69,14 @@ const model: ContentModel = {
 
 export function ContentEditor() {
   const [value, setValue] = useState<EntryValues>({});
-  return <EntryEditor model={model} value={value} onValueChange={setValue}
-    pickerItems={{ gallery: [{ id: "image-1", title: "Cover.jpg" }] }} />;
+  return (
+    <EntryEditor
+      model={model}
+      value={value}
+      onValueChange={setValue}
+      pickerItems={{ gallery: [{ id: "image-1", title: "Cover.jpg" }] }}
+    />
+  );
 }
 
 // Before saving: validateEntryValues(model, value) returns errors keyed by field ID.
@@ -73,6 +94,130 @@ Links open a URL modal from the toolbar or by clicking an existing body link. Sa
 
 Empty `TableBody` children automatically show “No data found.” across the table; override the text with `Table.emptyMessage`. Use `isEmpty` when custom row components determine whether there are results, or set it to `false` to suppress the message while the UI loads data. Loading indicators and skeleton rows are composed by the consuming UI. Standalone `TableEmpty` uses the same default message and supports a custom `title`. See the [upgrade guide example](UPGRADING.md#013).
 
+## App shell
+
+`AppShell` places a full-width `TopNav` above the desktop `SideNav` and a scrolling `main` landmark. Below 768px of **shell width**, a hamburger opens navigation in a right-side drawer. Its default height is `100dvh`; native `style`, `className`, div attributes, and a forwarded ref allow it to fit an embedded frame.
+
+```tsx
+import { AppShell, Avatar, SideNavItem, SideNavSection } from "@namroodinc/liquid-editorial";
+
+<AppShell
+  brand={<a href="/">Liquid</a>}
+  navigation={<>
+    <SideNavSection label="Workspace">
+      <SideNavItem icon="home" label="Home" href="/" />
+      <SideNavItem icon="file-text" label="Stories" href="/stories" isActive />
+    </SideNavSection>
+  </>}
+  actions={(location) => <>
+    <Avatar name="Ada Lovelace" size={32} />
+    {location === "drawer" && <span>Ada Lovelace</span>}
+  </>}
+>
+  <h1>Stories</h1>
+</AppShell>
+```
+
+Pass sections/items as `navigation`, without an enclosing SideNav, header, footer, or collapse control. Applications own destinations and `isActive`; AppShell closes the drawer when a navigation link is activated. `navigationLabel` defaults to `"Main"`. Keep shared application state outside the responsive slots and use React `useId` inside custom slot components that need IDs, since the desktop and drawer presentations can coexist during transitions.
+
+The optional `actions` render function receives `"topnav"` or `"drawer"`. Return a compact desktop control and an expanded mobile presentation; return nothing to omit the drawer footer. Keep this function pure. The component supplies no account, menu destinations, centre navigation, or space picker.
+
+The drawer traps focus and locks body scroll. Escape, Close, the scrim, and navigation links dismiss it and return focus to the hamburger. A popup inside it, such as a Menu in the actions footer, closes first on Escape. Modifier-key clicks that open a link elsewhere leave the drawer open. Widening the shell to desktop closes it and moves focus to the active desktop link when focus was inside the drawer. Reduced motion skips the transition.
+
+For other navigation compositions, `Drawer` supports `variant="navigation"`, a React-node `title`, `closeLabel`, and `portalContainer`. By default the drawer portals to `document.body` and covers the viewport; pass a positioned element to keep it inside that element. Supply `aria-label` for a dialog name independent of its visual brand. This variant retains an inert, accessibility-hidden panel during its closing transition; the default Drawer keeps its existing appearance and immediate unmounting.
+
+## Image cropping
+
+`ImageCropper` uses the library's custom engine with a fixed crop frame, diagonal background, shared `Slider` with a `Field` label/hint, and optional quarter-turn controls. Shared `Stack` components put the rotate/Reset buttons to the right of the zoom slider and wrap them below on narrow layouts. Supply one positive, finite `aspect` (width / height): `1` for an avatar, `16 / 9` for a cover, or `4 / 5` for a portrait.
+
+```tsx
+import { useState } from "react";
+import {
+  Button,
+  ImageCropper,
+  cropToBlob,
+  type CropRect,
+  type CropState,
+} from "@namroodinc/liquid-editorial";
+
+function CoverCropper({
+  src,
+  onSave,
+}: {
+  src: string;
+  onSave: (blob: Blob) => void;
+}) {
+  const [selection, setSelection] = useState<{
+    crop: CropRect;
+    state: CropState;
+  } | null>(null);
+
+  async function save() {
+    if (!selection) return;
+    const blob = await cropToBlob(src, selection.crop, {
+      outputWidth: 1600,
+      rotation: selection.state.rotation,
+      type: "image/jpeg",
+    });
+    onSave(blob);
+  }
+
+  return (
+    <>
+      <ImageCropper
+        src={src}
+        alt="Article cover"
+        aspect={16 / 9}
+        onChange={(crop, state) => setSelection({ crop, state })}
+      />
+      <Button isDisabled={!selection} onClick={save}>
+        Save crop
+      </Button>
+    </>
+  );
+}
+```
+
+Drag the image or focus the stage and use arrow keys (Shift for a larger step). The image always covers the fixed crop window; panning, zooming out, resizing, and rotation keep the crop inside the image. Zoom defaults to a maximum of `3`; set `maxZoom` to change it. Rotation is enabled by default; set `rotatable={false}` to hide its buttons. Reset clears pan, zoom, and rotation while retaining the supplied aspect.
+
+Changing `aspect` resets pan and zoom while preserving rotation. There is no ratio picker or implicit square default. `onChange(crop, state)` reports image-pixel coordinates plus pan, zoom, and quarter-turn rotation. `cropToBlob` supports same-origin or CORS-enabled sources and remains usable after unmounting with the saved crop/state. The forwarded ref and native HTML attributes apply to the outer container.
+
+Cropper.js has been removed; no third-party cropper initialization or styles are needed. Keep importing the library's `styles.css`. See [UPGRADING.md](UPGRADING.md#unreleased) for migration from the temporary native Cropper.js API or the earlier shape-picker API.
+
+## Pagination
+
+`Pagination` is controlled: keep the page and page size together in application state, and apply the single change callback. Import it from the package root or `@namroodinc/liquid-editorial/components/Pagination`.
+
+```tsx
+import { useState } from "react";
+import { Pagination, type PaginationState } from "@namroodinc/liquid-editorial";
+
+export function ArticlePagination({ totalResults }: { totalResults: number }) {
+  const [pagination, setPagination] = useState<PaginationState>({
+    page: 1,
+    pageSize: 25,
+  });
+
+  return (
+    <Pagination
+      totalResults={totalResults}
+      {...pagination}
+      onChange={setPagination}
+    />
+  );
+}
+```
+
+Pages are one-based. Changing the page size keeps the previously first visible result on the new page; for example, page 3 at 25 per page becomes page 2 at 50 per page. The callback emits `{ page, pageSize }` once per actual user change. Rendering new props emits no callback, and controls wait for the application to apply the new state.
+
+The default is a small bar with Previous/Next labels, a per-page selector with `[10, 25, 50, 100]`, and a range count. Navigation uses the standard neutral `Button` component and its shared sizing and interaction styles. Set `size="md"`, `showLabels={false}`, or `menuPlacement="top"` as needed. Controls wrap in reading order on narrow screens. All themes use the shared tokens, and the existing `styles.css` import includes pagination styles.
+
+Supply nonnegative integer totals, a positive integer page and page size, and a nonempty list of positive integer `pageSizeOptions` containing the current size. The displayed page and navigation targets are clamped to the available pages. Applications own data fetching, slicing, loading UI, and updating their canonical page after filtering or changing the total. Compose pagination beneath `Table` or another result view; it does not paginate children automatically.
+
+Zero results display “No results” and disable every control. `isDisabled` also disables everything. Boundary navigation buttons are disabled, and the size selector is disabled when the total is at most the smallest size option. Override the navigation's `aria-label` when rendering multiple pagination bars.
+
+`Select.menuPlacement` and `Popover.placement` also accept `"top"` or `"bottom"`; both default to `"bottom"` and flip when space requires it. A Select with `aria-labelledby` now shares that label with its listbox.
+
 ## Themes and fonts
 
 Set `data-theme` on the document root to `light`, `dark`, `cherry-glaze`, or `black-hawaii`. The default font tokens use system stacks and can be overridden by the consumer without downloading bundled font files:

package/UPGRADING.md

@@ -2,25 +2,145 @@
 
 ## Unreleased
 
-## 0.1.5
+## 0.1.7
 
 ### Changes
 
+- Added `AppShell`, composing a full-width TopNav above SideNav and a scrolling main landmark. Below 768px of shell width, navigation opens in a right-side drawer with a branded header and an optional actions footer.
+- Added Drawer `variant="navigation"`, React-node titles, `closeLabel`, and `portalContainer`. The navigation variant focuses Close first, slides/fades over `--duration-panel`, and retains an inert, accessibility-hidden panel until its exit completes. Explicit `aria-label` names the dialog instead of the visual title.
+- Rebuilt the combined navigation example to match the App Shell handoff, with fullscreen, narrow, no-actions, and long-content stories. Standalone navigation components remain available.
+- Fixed mobile navigation moving the underlying page during its slide-in. Navigation drawers clip their off-screen panel and move/restore focus without scrolling the shell.
+- Audited the library and examples and replaced custom button markup with shared `Button`: shell/drawer/sidebar controls, field clear/remove/step actions, drag handles, menus, selection rows, calendar/Select options, date/select triggers, Switch, and interactive Stepper/SubNav controls. Removed duplicate action-button styling. A contributor lint rule rejects raw buttons outside Button and test fixtures.
+- Icon-only Button now supports custom visual children when `iconStart` is absent, including Avatar and numeric calendar/progress glyphs. Pending state replaces those children with the shared spinner. Select/DateField retain the shared Field skin; Switch retains its track/knob mechanics.
+- Added Button `size="xs"` (24px) for compact actions inside fields and chips. SearchField clear and TagsInput remove use it, so tags no longer make an md TagsInput taller and the clear button fits a small SearchField.
+- Navigation Drawer covers the viewport, above page chrome, unless `portalContainer` is supplied. With a container, it stays inside that positioned element (AppShell does this). `side="start"` and right-to-left documents now slide out through the panel's own edge. Reduced motion applies to the panel, and panel content that does not scroll itself can scroll.
+- Drawer lets popups inside it handle Escape first. Menu, Select, DateField, and Modal mark the Escape they handle with `preventDefault()`, so closing a menu in AppShell's drawer footer leaves the drawer open.
+- AppShell renders without `ResizeObserver`. Modifier-key, non-primary-button, and `target="_blank"` link clicks no longer close its drawer.
+- Fixed regressions from the Button migration. AssetTile hover and press no longer paint over the thumbnail. Interactive Stepper markers match the rail's marker size. Calendar days outside the shown month are muted again. MenuItem labels wrap, and danger shortcuts use the item's text colour. Board handles show the grab cursor with the aggregate stylesheet. SubNavButton keeps `.ds-subnav__item` and the SubNav rail. Drag overlays draw a decorative grip instead of a hidden button.
+
+### Adoption
+
+Import `AppShell` from the root or `@namroodinc/liquid-editorial/components/AppShell`, retaining the existing aggregate CSS import. Move the product brand into `brand`, pass SideNavSection/SideNavItem content as `navigation`, and put page content directly inside AppShell. Do not wrap navigation in another SideNav or add a SideNavHeader/collapse toggle. The shell supplies the main landmark, so remove any enclosing/nested main from the replaced layout.
+
+Keep routes and active links in application state. Supply `actions={(location) => ...}` to render compact `"topnav"` controls and expanded `"drawer"` content. Omit the prop, or return nothing for the drawer, to omit its footer. Use `navigationLabel` to change the default `"Main"` name. Keep render callbacks pure and shared state outside slots; use React `useId` inside custom components instead of fixed IDs in content rendered in both locations.
+
+AppShell defaults to `100dvh`; override its height through native style/className for embedded frames. It responds to its own width with CSS container queries. The library owns drawer state and dismisses it on link activation and when the shell reaches 768px; no router dependency or prototype viewport prop is needed. The page-movement fix requires no prop changes; remove any local shell-scroll reset workaround added for the drawer animation.
+
+The Button cleanup needs no changes to existing component props. Remove local copies of button appearance and selectors for removed `.ds-search__clear`, `.ds-tags__remove`, and `.ds-asset-tile__hit-label` markup. Use accessible names in tests. Compose custom square controls as `<Button isIconOnly aria-label="Account">...</Button>` with no `iconStart`, using `aria-label` or `aria-labelledby` for their accessible name. New library controls and examples must compose Button; the existing variants/sizes supply their appearance. Shared field skin and specialized widget layout remain supported. Use `size="xs"` for a Button placed inside a field or chip.
+
+Use `Drawer variant="navigation"` without `portalContainer` to cover the viewport. To contain it in a layout region, pass a positioned element (for example, `position: relative`) as `portalContainer`. If a custom popup inside a Drawer handles Escape, call `event.preventDefault()` so the drawer stays open. Remove any ResizeObserver polyfill that was added only for AppShell.
+
+### Compatibility
+
+The AppShell/Drawer props are additive. The Button cleanup intentionally standardizes action appearance and sizes: shell navigation controls use large 48px Buttons; clear/remove actions use extra-small 24px Buttons and drag handles use small Buttons; numeric steppers follow their field's standard Button size. Menu danger actions use the shared danger variant. SubNavButton composes Button but keeps the SubNav rail and its `.ds-subnav__item` class. Interactive Stepper markers are square Buttons at the rail's marker size, while read-only markers remain indicators. `ButtonSize` now includes `"xs"`; TypeScript maps keyed by every `ButtonSize` need an `xs` entry. Drawer handles Escape and Tab on `window`, so keyboard events dispatched on `document` or on any element still reach it. An Escape already marked with `preventDefault()` no longer closes it. Select now ignores Escape while its listbox is closed, so an enclosing Drawer can close. Select option rows are now disabled-capable button elements with `role="option"`; selection and keyboard contracts are unchanged. Custom icon-only children that were previously hidden now render when no `iconStart` is supplied. Default Drawer dismissal timing and string titles remain supported. Navigation Drawer exits remain in the DOM briefly but are immediately inert and hidden from accessibility queries; tests that require actual removal should await the transition. Closed shells render on the server without accessing browser globals. Supported React versions and package versions are unchanged; the release workflow owns version increments. There is no new runtime dependency.
+
+### Verification
+
+Check 390px, 767px, 768px, and 1280px shell widths, including a narrow shell inside a wide viewport. Confirm the top bar spans the whole frame, the desktop rail has no brand/collapse header, content and navigation scroll independently, and the mobile footer appears only with actions. During opening and closing, confirm only the panel moves: the background frame and shell scroll offsets must stay fixed, including when main content is already scrolled. Test Escape, Close, scrim and link dismissal, initial Close focus, Tab/Shift+Tab trapping, focus restoration, body scroll restoration, desktop resize while open, reduced motion, and reopening during exit. Check multiple shell IDs and the consuming application's route/active-state behavior. Run the consuming project's typecheck, tests, and build after replacing its layout.
+
+Open the navigation drawer in a narrow AppShell. Press Escape inside an actions Menu or Select and confirm only the popup closes. Cmd/Ctrl-click a navigation link and confirm the drawer stays open. Outside AppShell, open `Drawer variant="navigation"` on a scrolled page without `portalContainer`, and also with `side="start"`, `dir="rtl"`, reduced motion, and content taller than the panel. Run consuming tests that render AppShell without a ResizeObserver polyfill.
+
+Compare the converted ordinary actions with standalone Buttons of the same size/variant, including keyboard focus and disabled state. Hover and press a selectable AssetTile and confirm the thumbnail stays visible. Check navigable Steppers at both sizes: connectors should run through marker centres, with labels level. Check calendar spill-over days, wrapped and danger MenuItems, Board grab cursors with the built aggregate CSS, SubNavs that mix links and buttons, tag chips in md TagsInput, and the clear button in a small SearchField. Check field clear/remove/step behavior, select/date validation and selection, disabled options, Switch state, menu actions, SubNav/Stepper activation, and pointer/keyboard dragging. Verify tag wrapping, calendar layout, and long selection rows at narrow widths and in every theme. Run library lint to enforce Button composition.
+
+## 0.1.6
+
+### Changes
+
+- ImageCropper places rotate/Reset buttons to the right of the zoom slider, vertically centred on its track. The shared controls wrap onto another row when space is limited.
+
 - Pushes to `main`, including merged PRs, now automatically bump the patch version and publish the package to npm after validation.
 - The release workflow moves these notes under the new version and commits the version files and guide back to `main`.
+- Added controlled `Pagination` with standard neutral Previous/Next `Button`s, a per-page dropdown, a live result range, and wrapping layouts for narrow screens. Pagination supplies layout styles and uses the shared controls' appearance.
+- Added optional `Select.menuPlacement` and `Popover.placement` (`"top"` or `"bottom"`). Select listboxes now share a trigger's `aria-labelledby` when supplied.
+- Simplified `ImageCropper` to one required `aspect` prop controlled by the application. Removed the ratio picker, `ratios`, `onAspectChange`, and the `cropRatios` / `CropRatio` exports.
+- ImageCropper composes shared `Stack`, `Field`, `Slider`, `ButtonGroup`, and `Button` components. Removed duplicate layout, label, hint, value, and slider styling; its CSS now covers only the crop surface, image, frame, and guides.
+- Restored ImageCropper's custom engine, fixed crop frame, diagonal background, zoom slider, rotation buttons, and crop/state export API. Image boundaries remain enforced when panning, zooming out, rotating, or resizing. Removed Cropper.js and the temporary native `onReady` API.
 
 ### Adoption
 
 Library contributors add upgrade guidance here and merge their changes to `main`. GitHub Actions handles versioning, validation, and publishing; there are no local npm release commands or manual GitHub Releases to create. Pull the generated version commit before continuing local work. Consuming applications can update the dependency as usual.
 
+To adopt pagination, import `Pagination` from the package root or `@namroodinc/liquid-editorial/components/Pagination` and keep both values in application state:
+
+```tsx
+const [pagination, setPagination] = useState({ page: 1, pageSize: 25 });
+
+<Pagination
+  totalResults={totalResults}
+  {...pagination}
+  onChange={setPagination}
+/>;
+```
+
+Use the emitted page and page size together for requests or local slicing. Changing size preserves the first visible result (page 3 at size 25 becomes page 2 at size 50). Keep canonical state in bounds when filtering changes the total; prop changes do not emit corrections. Supply valid counts and positive integer sizes, with a nonempty `pageSizeOptions` containing the current size. The defaults are `[10, 25, 50, 100]`. The component handles no data loading or slicing; compose it beneath a table or another result view. The existing aggregate CSS import includes its styles. Give multiple pagination bars distinct `aria-label` values.
+
+Use `menuPlacement="top"` on Pagination or Select, or `placement="top"` on Popover, to prefer an upward menu. Space constraints can still flip the panel to the other side.
+
+Remove any `showFirstLast` or `joinedButtons` props from local integrations of the unreleased component. Pagination provides Previous/Next navigation only; First/Last controls and button joining are no longer part of its API.
+
+Update every `ImageCropper` call to supply a positive, finite `aspect` (width / height):
+
+```tsx
+import { useState } from "react";
+import {
+  cropToBlob,
+  type CropRect,
+  type CropState,
+} from "@namroodinc/liquid-editorial";
+
+const [selection, setSelection] = useState<{
+  crop: CropRect;
+  state: CropState;
+} | null>(null);
+<ImageCropper
+  src={src}
+  aspect={16 / 9}
+  onChange={(crop, state) => setSelection({ crop, state })}
+/>;
+
+// In your save handler:
+if (selection) {
+  const blob = await cropToBlob(src, selection.crop, {
+    outputWidth: 1600,
+    rotation: selection.state.rotation,
+    type: "image/jpeg",
+  });
+  uploadCrop(blob);
+}
+```
+
+Use `aspect={1}` to retain the former implicit square shape. Remove `ratios`, `onAspectChange`, `cropRatios`, and `CropRatio` usage. The application owns the destination shape; changing `aspect` resets pan/zoom and preserves rotation. Reset clears pan, zoom, and rotation while keeping that aspect.
+
+If adopting local versions of the temporary Cropper.js integration, remove `onReady`, native Cropper type imports, and `$toCanvas()` usage. Use the restored `onChange(crop, state)` callback, `CropRect` / `CropState` types, and `cropToBlob(src, crop, { rotation: state.rotation })`. `CropToBlobOptions`, `maxZoom` (default `3`), and `rotatable` (default `true`) are restored. The standalone helper supports saved crops after unmounting and requires same-origin or CORS-enabled sources. Remove any direct Cropper.js dependency or styles added solely for this component.
+
+Keep the library CSS import for the diagonal background, fixed frame, guides, shared Slider/Field, and standard Button controls. Zoom is labelled by the shared Field and displays Slider's standard value label (for example, `1×` or `1.25×`). No prop changes are needed. The instruction text now uses Field's hint and is associated with the Zoom slider through `aria-describedby`. The zoom slider and rotate/Reset buttons share a horizontal Stack, with actions to the right and the Field hint beneath the row. The actions wrap below the slider in narrow containers. Remove selectors for `.ds-cropper__controls`, `.ds-cropper__zoom`, `.ds-cropper__hint`, `.ds-cropper__slider`, `.ds-cropper__zoom-label`, and `.ds-cropper__value`; use accessible names when testing controls. The forwarded ref and native container attributes remain supported. Tests should exercise the stage's direct image and the library's controls; there are no Cropper.js elements or native movable/resizable selections.
+
 ### Compatibility
 
-The workflow publishes stable patch releases under `latest`. Creating a GitHub Release no longer triggers publishing. Component APIs are unchanged.
+The ImageCropper control-row adjustment needs no adoption changes. It uses the existing Field, Slider, Stack, ButtonGroup, and Button components; control appearance, accessible associations, zoom values, and crop APIs are unchanged.
+
+The workflow publishes stable patch releases under `latest`. Creating a GitHub Release no longer triggers publishing.
+
+Pagination is an additive API and requires `totalResults`, `page`, `pageSize`, and `onChange({ page, pageSize })`; it has no uncontrolled mode or implicit result total. The new placement props are optional and retain the previous bottom-first behavior. Select listboxes with `aria-labelledby` now use the visible external label instead of the placeholder; update accessibility assertions that expected the placeholder in that case. The manifest and lockfile versions are unchanged; the release workflow performs the version bump.
+
+The required single-aspect API is the remaining ImageCropper breaking change: `aspect` is required and the ratio picker, `ratios`, `onAspectChange`, `cropRatios`, and `CropRatio` are removed. Existing `CropRect`, `CropState`, `CropToBlobOptions`, `onChange`, `maxZoom`, `rotatable`, and `cropToBlob` contracts remain supported. Image-pixel coordinates are rounded and clamped inside the rotated source bounds.
+
+The temporary Cropper.js integration is reverted. Its dependency, `onReady` callback, and native export workflow are removed. The fixed frame, rotation controls, theme-driven diagonal background, and custom engine are restored. Root/component imports, ESM/CommonJS, SSR, and React 18/19 remain supported. Styles are supplied through the library CSS entry points. The shared Slider/Field composition changes only the zoom control presentation and DOM; zoom bounds, step, crop callbacks, and the public API remain unchanged.
 
 ### Verification
 
 Check the `Publish to npm` workflow in GitHub Actions and confirm that the new version appears on the npm package page. The workflow runs the existing full validation before committing and publishing.
 
+- In consuming applications, verify first/last pages, partial last pages, zero results, custom size options, disabled/loading UI, and state correction after filtering.
+- Change the size while on a later page and confirm that the first visible result remains on the new page and one callback updates both values.
+- Exercise keyboard selection, Escape/Tab dismissal, focus, and accessible labels, including when two pagination bars are present.
+- Check narrow layouts, themes, upward menu placement, and viewport flipping. Confirm Previous/Next match standard neutral Buttons of the same size and that First/Last controls are absent. Run the consuming project's type checks, tests, and build with its existing CSS import.
+- Verify ImageCropper's rotate/Reset buttons sit to the right of the slider on wide layouts and wrap below it without overflow in narrow containers, including with rotation disabled.
+- Confirm ImageCropper's Zoom slider has its visible Field label, associated Field hint, and standard Slider appearance/value label. Adjust it by pointer and keyboard, then check Reset and rotation update its controlled value. Check narrow layouts and all themes, including multiple instances with distinct label associations.
+- For ImageCropper, check square, landscape, and portrait aspects. Confirm the fixed frame, diagonal background, zoom slider, rotation buttons, and Reset are present, and the ratio picker is absent.
+- Pan to every boundary, zoom back out, lower `maxZoom`, rotate through quarter turns, and resize the stage. Confirm the frame stays covered and emitted crop coordinates remain inside the rotated source dimensions. Change `aspect` after pan/zoom/rotation and confirm only rotation is retained.
+- Exercise mouse/touch dragging, keyboard nudges, multiple instances, optional rotation, and all themes. Export crops using `cropToBlob`, including a saved crop after unmounting, and check dimensions and image pixels. Run the consuming project's type checks, tests, build, and SSR/import checks.
+
 ## 0.1.3
 
 ### Changes
@@ -35,8 +155,11 @@ Use the shared empty message while keeping loading indicators in your applicatio
 
 ```tsx
 <TableFrame>
-  <Table emptyMessage="No matching articles."
-    isEmpty={!isLoading && articles.length === 0} aria-busy={isLoading}>
+  <Table
+    emptyMessage="No matching articles."
+    isEmpty={!isLoading && articles.length === 0}
+    aria-busy={isLoading}
+  >
     <TableHead>
       <TableRow>
         <TableHeaderCell>Title</TableHeaderCell>

package/dist/components/AppShell/index.cjs

@@ -0,0 +1,2 @@
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});const e=require("../Button/index.cjs"),t=require("../Drawer/index.cjs"),n=require("../SideNav/index.cjs"),r=require("../TopNav/index.cjs");let i=require("react"),a=require("react/jsx-runtime");var o=(0,i.forwardRef)(function({brand:o,navigation:s,actions:c,navigationLabel:l=`Main`,className:u,children:d,...f},p){let[m,h]=(0,i.useState)(null),[g,_]=(0,i.useState)(!1),v=(0,i.useRef)(null),y=(0,i.useRef)(null),b=(0,i.useRef)(!1),x=(0,i.useId)(),S=(0,i.useCallback)(e=>{h(e),typeof p==`function`?p(e):p&&(p.current=e)},[p]);(0,i.useEffect)(()=>{if(!m)return;let e=e=>{e<768||(m.querySelector(`[data-state='open'] [role='dialog']`)?.contains(document.activeElement)&&(b.current=!0),_(!1))};if(e(m.getBoundingClientRect().width),typeof ResizeObserver>`u`)return;let t=new ResizeObserver(([t])=>{t&&e(t.contentRect.width)});return t.observe(m),()=>{t.disconnect()}},[m]),(0,i.useEffect)(()=>{!g&&b.current&&(b.current=!1,(v.current?.querySelector(`[aria-current='page']`)??v.current?.querySelector(`a[href]`)??y.current)?.focus())},[g]);let C=c?.(`drawer`);return(0,a.jsxs)(`div`,{...f,ref:S,className:[`ds-appshell`,u].filter(Boolean).join(` `),children:[(0,a.jsxs)(`div`,{className:`ds-appshell__frame`,"aria-hidden":g||void 0,ref:e=>{e&&(e.inert=g)},children:[(0,a.jsx)(r.TopNav,{brand:o,actions:(0,a.jsxs)(a.Fragment,{children:[(0,a.jsx)(`div`,{className:`ds-appshell__actions`,children:c?.(`topnav`)}),(0,a.jsx)(e.Button,{variant:`simple`,size:`lg`,isIconOnly:!0,iconStart:`menu`,className:`ds-appshell__toggle`,"aria-label":`Open navigation`,"aria-expanded":g,"aria-controls":x,onClick:()=>_(!0)})]})}),(0,a.jsxs)(`div`,{className:`ds-appshell__body`,children:[(0,a.jsx)(n.SideNav,{ref:v,className:`ds-appshell__desktop-nav`,label:l,children:s}),(0,a.jsx)(`main`,{ref:y,className:`ds-appshell__main`,tabIndex:-1,children:d})]})]}),(0,a.jsx)(t.Drawer,{id:x,isOpen:g,onClose:()=>_(!1),variant:`navigation`,portalContainer:m,title:o,"aria-label":`Navigation`,closeLabel:`Close navigation`,footer:C?(0,a.jsx)(n.SideNavFooter,{children:C}):void 0,children:(0,a.jsx)(n.SideNav,{className:`ds-appshell__mobile-nav`,label:l,onClick:e=>{let t=e.target instanceof Element?e.target.closest(`a[href]`):null,n=e.button!==0||e.metaKey||e.ctrlKey||e.shiftKey||e.altKey||t?.target===`_blank`;t&&!n&&_(!1)},children:s})})]})});exports.AppShell=o;
+//# sourceMappingURL=index.cjs.map

package/dist/components/AppShell/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","names":["forwardRef","useState","useRef","useId","useCallback","TopNav","_Fragment","Button","SideNav","Drawer","SideNavFooter","require_components_Button_index","require_components_Drawer_index","require_components_SideNav_index","require_components_TopNav_index","react","react_jsx_runtime","AppShell","rest","shell","setShell","isOpen","setOpen","desktopNavRef","mainRef","restoreDesktopFocus","drawerId","shellRef","node","ref","measure","width","observer","entry","drawerActions","actions","className","navigationLabel","navigation","brand","link","event","opensElsewhere"],"sources":["../../../src/components/AppShell/index.tsx"],"sourcesContent":["import {\n  forwardRef,\n  useCallback,\n  useEffect,\n  useId,\n  useRef,\n  useState,\n  type HTMLAttributes,\n  type ReactNode,\n} from \"react\";\nimport { Drawer } from \"../Drawer\";\nimport { Button } from \"../Button\";\nimport { SideNav, SideNavFooter } from \"../SideNav\";\nimport { TopNav } from \"../TopNav\";\nimport \"./style.css\";\n\nexport interface AppShellProps extends HTMLAttributes<HTMLDivElement> {\n  /** Product brand, shared by the top bar and mobile drawer header. */\n  brand: ReactNode;\n  /** SideNavSection/SideNavItem content. The application owns routing and selection. */\n  navigation: ReactNode;\n  /** One slot with a compact top-bar and expanded drawer presentation. */\n  actions?: (location: \"topnav\" | \"drawer\") => ReactNode;\n  navigationLabel?: string;\n  /** Rendered inside the shell's scrolling main landmark. */\n  children?: ReactNode;\n}\n\n/** Full-width product bar above a desktop rail, or a mobile navigation drawer. */\nexport const AppShell = forwardRef<HTMLDivElement, AppShellProps>(function AppShell(\n  { brand, navigation, actions, navigationLabel = \"Main\", className, children, ...rest },\n  ref,\n) {\n  const [shell, setShell] = useState<HTMLDivElement | null>(null);\n  const [isOpen, setOpen] = useState(false);\n  const desktopNavRef = useRef<HTMLElement | null>(null);\n  const mainRef = useRef<HTMLElement | null>(null);\n  const restoreDesktopFocus = useRef(false);\n  const drawerId = useId();\n  const shellRef = useCallback((node: HTMLDivElement | null) => {\n    setShell(node);\n    if (typeof ref === \"function\") ref(node);\n    else if (ref) ref.current = node;\n  }, [ref]);\n\n  useEffect(() => {\n    if (!shell) return;\n    const measure = (width: number) => {\n      if (width < 768) return;\n      const focusInDrawer = shell.querySelector(\"[data-state='open'] [role='dialog']\")?.contains(document.activeElement);\n      if (focusInDrawer) restoreDesktopFocus.current = true;\n      setOpen(false);\n    };\n    measure(shell.getBoundingClientRect().width);\n    if (typeof ResizeObserver === \"undefined\") return;\n    const observer = new ResizeObserver(([entry]) => {\n      if (entry) measure(entry.contentRect.width);\n    });\n    observer.observe(shell);\n    return () => {\n      observer.disconnect();\n    };\n  }, [shell]);\n\n  useEffect(() => {\n    if (isOpen || !restoreDesktopFocus.current) return;\n    restoreDesktopFocus.current = false;\n    const destination = desktopNavRef.current?.querySelector<HTMLElement>(\"[aria-current='page']\")\n      ?? desktopNavRef.current?.querySelector<HTMLElement>(\"a[href]\");\n    (destination ?? mainRef.current)?.focus();\n  }, [isOpen]);\n\n  const drawerActions = actions?.(\"drawer\");\n\n  return (\n    <div {...rest} ref={shellRef} className={[\"ds-appshell\", className].filter(Boolean).join(\" \")}>\n      <div\n        className=\"ds-appshell__frame\"\n        aria-hidden={isOpen || undefined}\n        ref={(node) => { if (node) node.inert = isOpen; }}\n      >\n        <TopNav\n          brand={brand}\n          actions={<>\n            <div className=\"ds-appshell__actions\">{actions?.(\"topnav\")}</div>\n            <Button\n              variant=\"simple\"\n              size=\"lg\"\n              isIconOnly\n              iconStart=\"menu\"\n              className=\"ds-appshell__toggle\"\n              aria-label=\"Open navigation\"\n              aria-expanded={isOpen}\n              aria-controls={drawerId}\n              onClick={() => setOpen(true)}\n            />\n          </>}\n        />\n        <div className=\"ds-appshell__body\">\n          <SideNav ref={desktopNavRef} className=\"ds-appshell__desktop-nav\" label={navigationLabel}>\n            {navigation}\n          </SideNav>\n          <main ref={mainRef} className=\"ds-appshell__main\" tabIndex={-1}>{children}</main>\n        </div>\n      </div>\n      <Drawer\n        id={drawerId}\n        isOpen={isOpen}\n        onClose={() => setOpen(false)}\n        variant=\"navigation\"\n        portalContainer={shell}\n        title={brand}\n        aria-label=\"Navigation\"\n        closeLabel=\"Close navigation\"\n        footer={drawerActions ? <SideNavFooter>{drawerActions}</SideNavFooter> : undefined}\n      >\n        <SideNav\n          className=\"ds-appshell__mobile-nav\"\n          label={navigationLabel}\n          onClick={(event) => {\n            const link = event.target instanceof Element ? event.target.closest<HTMLAnchorElement>(\"a[href]\") : null;\n            // Opening a link elsewhere (modifier keys, another button, a new tab) leaves this page in place.\n            const opensElsewhere = event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey\n              || event.altKey || link?.target === \"_blank\";\n            if (link && !opensElsewhere) setOpen(false);\n          }}\n        >\n          {navigation}\n        </SideNav>\n      </Drawer>\n    </div>\n  );\n});\n"],"mappings":"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"}

package/dist/components/AppShell/index.d.cts

@@ -0,0 +1,15 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+export interface AppShellProps extends HTMLAttributes<HTMLDivElement> {
+    /** Product brand, shared by the top bar and mobile drawer header. */
+    brand: ReactNode;
+    /** SideNavSection/SideNavItem content. The application owns routing and selection. */
+    navigation: ReactNode;
+    /** One slot with a compact top-bar and expanded drawer presentation. */
+    actions?: (location: "topnav" | "drawer") => ReactNode;
+    navigationLabel?: string;
+    /** Rendered inside the shell's scrolling main landmark. */
+    children?: ReactNode;
+}
+/** Full-width product bar above a desktop rail, or a mobile navigation drawer. */
+export declare const AppShell: import("react").ForwardRefExoticComponent<AppShellProps & import("react").RefAttributes<HTMLDivElement>>;
+//# sourceMappingURL=index.d.cts.map

package/dist/components/AppShell/index.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.cts","sourceRoot":"","sources":["../../../src/components/AppShell/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,cAAc,EACnB,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAKf,OAAO,aAAa,CAAC;AAErB,MAAM,WAAW,aAAc,SAAQ,cAAc,CAAC,cAAc,CAAC;IACnE,qEAAqE;IACrE,KAAK,EAAE,SAAS,CAAC;IACjB,sFAAsF;IACtF,UAAU,EAAE,SAAS,CAAC;IACtB,wEAAwE;IACxE,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,GAAG,QAAQ,KAAK,SAAS,CAAC;IACvD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED,kFAAkF;AAClF,eAAO,MAAM,QAAQ,0GAuGnB,CAAC"}

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

@@ -0,0 +1,15 @@
+import { type HTMLAttributes, type ReactNode } from "react";
+export interface AppShellProps extends HTMLAttributes<HTMLDivElement> {
+    /** Product brand, shared by the top bar and mobile drawer header. */
+    brand: ReactNode;
+    /** SideNavSection/SideNavItem content. The application owns routing and selection. */
+    navigation: ReactNode;
+    /** One slot with a compact top-bar and expanded drawer presentation. */
+    actions?: (location: "topnav" | "drawer") => ReactNode;
+    navigationLabel?: string;
+    /** Rendered inside the shell's scrolling main landmark. */
+    children?: ReactNode;
+}
+/** Full-width product bar above a desktop rail, or a mobile navigation drawer. */
+export declare const AppShell: import("react").ForwardRefExoticComponent<AppShellProps & import("react").RefAttributes<HTMLDivElement>>;
+//# sourceMappingURL=index.d.ts.map

package/dist/components/AppShell/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/AppShell/index.tsx"],"names":[],"mappings":"AAAA,OAAO,EAOL,KAAK,cAAc,EACnB,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAKf,OAAO,aAAa,CAAC;AAErB,MAAM,WAAW,aAAc,SAAQ,cAAc,CAAC,cAAc,CAAC;IACnE,qEAAqE;IACrE,KAAK,EAAE,SAAS,CAAC;IACjB,sFAAsF;IACtF,UAAU,EAAE,SAAS,CAAC;IACtB,wEAAwE;IACxE,OAAO,CAAC,EAAE,CAAC,QAAQ,EAAE,QAAQ,GAAG,QAAQ,KAAK,SAAS,CAAC;IACvD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,2DAA2D;IAC3D,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED,kFAAkF;AAClF,eAAO,MAAM,QAAQ,0GAuGnB,CAAC"}

package/dist/components/AppShell/index.js

@@ -0,0 +1,93 @@
+import { Button as e } from "../Button/index.js";
+import { Drawer as t } from "../Drawer/index.js";
+import { SideNav as n, SideNavFooter as r } from "../SideNav/index.js";
+import { TopNav as i } from "../TopNav/index.js";
+import { forwardRef as a, useCallback as o, useEffect as s, useId as c, useRef as l, useState as u } from "react";
+import { Fragment as d, jsx as f, jsxs as p } from "react/jsx-runtime";
+//#region src/components/AppShell/index.tsx
+var m = a(function({ brand: a, navigation: m, actions: h, navigationLabel: g = "Main", className: _, children: v, ...y }, b) {
+	let [x, S] = u(null), [C, w] = u(!1), T = l(null), E = l(null), D = l(!1), O = c(), k = o((e) => {
+		S(e), typeof b == "function" ? b(e) : b && (b.current = e);
+	}, [b]);
+	s(() => {
+		if (!x) return;
+		let e = (e) => {
+			e < 768 || (x.querySelector("[data-state='open'] [role='dialog']")?.contains(document.activeElement) && (D.current = !0), w(!1));
+		};
+		if (e(x.getBoundingClientRect().width), typeof ResizeObserver > "u") return;
+		let t = new ResizeObserver(([t]) => {
+			t && e(t.contentRect.width);
+		});
+		return t.observe(x), () => {
+			t.disconnect();
+		};
+	}, [x]), s(() => {
+		!C && D.current && (D.current = !1, (T.current?.querySelector("[aria-current='page']") ?? T.current?.querySelector("a[href]") ?? E.current)?.focus());
+	}, [C]);
+	let A = h?.("drawer");
+	return /* @__PURE__ */ p("div", {
+		...y,
+		ref: k,
+		className: ["ds-appshell", _].filter(Boolean).join(" "),
+		children: [/* @__PURE__ */ p("div", {
+			className: "ds-appshell__frame",
+			"aria-hidden": C || void 0,
+			ref: (e) => {
+				e && (e.inert = C);
+			},
+			children: [/* @__PURE__ */ f(i, {
+				brand: a,
+				actions: /* @__PURE__ */ p(d, { children: [/* @__PURE__ */ f("div", {
+					className: "ds-appshell__actions",
+					children: h?.("topnav")
+				}), /* @__PURE__ */ f(e, {
+					variant: "simple",
+					size: "lg",
+					isIconOnly: !0,
+					iconStart: "menu",
+					className: "ds-appshell__toggle",
+					"aria-label": "Open navigation",
+					"aria-expanded": C,
+					"aria-controls": O,
+					onClick: () => w(!0)
+				})] })
+			}), /* @__PURE__ */ p("div", {
+				className: "ds-appshell__body",
+				children: [/* @__PURE__ */ f(n, {
+					ref: T,
+					className: "ds-appshell__desktop-nav",
+					label: g,
+					children: m
+				}), /* @__PURE__ */ f("main", {
+					ref: E,
+					className: "ds-appshell__main",
+					tabIndex: -1,
+					children: v
+				})]
+			})]
+		}), /* @__PURE__ */ f(t, {
+			id: O,
+			isOpen: C,
+			onClose: () => w(!1),
+			variant: "navigation",
+			portalContainer: x,
+			title: a,
+			"aria-label": "Navigation",
+			closeLabel: "Close navigation",
+			footer: A ? /* @__PURE__ */ f(r, { children: A }) : void 0,
+			children: /* @__PURE__ */ f(n, {
+				className: "ds-appshell__mobile-nav",
+				label: g,
+				onClick: (e) => {
+					let t = e.target instanceof Element ? e.target.closest("a[href]") : null, n = e.button !== 0 || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || t?.target === "_blank";
+					t && !n && w(!1);
+				},
+				children: m
+			})
+		})]
+	});
+});
+//#endregion
+export { m as AppShell };
+
+//# sourceMappingURL=index.js.map

package/dist/components/AppShell/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":["_Fragment","Fragment$1","AppShell","forwardRef","rest","shell","setShell","useState","isOpen","setOpen","desktopNavRef","useRef","mainRef","restoreDesktopFocus","drawerId","useId","shellRef","useCallback","node","ref","useEffect","measure","width","observer","entry","drawerActions","actions","className","TopNav","Button","SideNav","navigationLabel","navigation","Drawer","brand","SideNavFooter","link","event","opensElsewhere"],"sources":["../../../src/components/AppShell/index.tsx"],"sourcesContent":["import {\n  forwardRef,\n  useCallback,\n  useEffect,\n  useId,\n  useRef,\n  useState,\n  type HTMLAttributes,\n  type ReactNode,\n} from \"react\";\nimport { Drawer } from \"../Drawer\";\nimport { Button } from \"../Button\";\nimport { SideNav, SideNavFooter } from \"../SideNav\";\nimport { TopNav } from \"../TopNav\";\nimport \"./style.css\";\n\nexport interface AppShellProps extends HTMLAttributes<HTMLDivElement> {\n  /** Product brand, shared by the top bar and mobile drawer header. */\n  brand: ReactNode;\n  /** SideNavSection/SideNavItem content. The application owns routing and selection. */\n  navigation: ReactNode;\n  /** One slot with a compact top-bar and expanded drawer presentation. */\n  actions?: (location: \"topnav\" | \"drawer\") => ReactNode;\n  navigationLabel?: string;\n  /** Rendered inside the shell's scrolling main landmark. */\n  children?: ReactNode;\n}\n\n/** Full-width product bar above a desktop rail, or a mobile navigation drawer. */\nexport const AppShell = forwardRef<HTMLDivElement, AppShellProps>(function AppShell(\n  { brand, navigation, actions, navigationLabel = \"Main\", className, children, ...rest },\n  ref,\n) {\n  const [shell, setShell] = useState<HTMLDivElement | null>(null);\n  const [isOpen, setOpen] = useState(false);\n  const desktopNavRef = useRef<HTMLElement | null>(null);\n  const mainRef = useRef<HTMLElement | null>(null);\n  const restoreDesktopFocus = useRef(false);\n  const drawerId = useId();\n  const shellRef = useCallback((node: HTMLDivElement | null) => {\n    setShell(node);\n    if (typeof ref === \"function\") ref(node);\n    else if (ref) ref.current = node;\n  }, [ref]);\n\n  useEffect(() => {\n    if (!shell) return;\n    const measure = (width: number) => {\n      if (width < 768) return;\n      const focusInDrawer = shell.querySelector(\"[data-state='open'] [role='dialog']\")?.contains(document.activeElement);\n      if (focusInDrawer) restoreDesktopFocus.current = true;\n      setOpen(false);\n    };\n    measure(shell.getBoundingClientRect().width);\n    if (typeof ResizeObserver === \"undefined\") return;\n    const observer = new ResizeObserver(([entry]) => {\n      if (entry) measure(entry.contentRect.width);\n    });\n    observer.observe(shell);\n    return () => {\n      observer.disconnect();\n    };\n  }, [shell]);\n\n  useEffect(() => {\n    if (isOpen || !restoreDesktopFocus.current) return;\n    restoreDesktopFocus.current = false;\n    const destination = desktopNavRef.current?.querySelector<HTMLElement>(\"[aria-current='page']\")\n      ?? desktopNavRef.current?.querySelector<HTMLElement>(\"a[href]\");\n    (destination ?? mainRef.current)?.focus();\n  }, [isOpen]);\n\n  const drawerActions = actions?.(\"drawer\");\n\n  return (\n    <div {...rest} ref={shellRef} className={[\"ds-appshell\", className].filter(Boolean).join(\" \")}>\n      <div\n        className=\"ds-appshell__frame\"\n        aria-hidden={isOpen || undefined}\n        ref={(node) => { if (node) node.inert = isOpen; }}\n      >\n        <TopNav\n          brand={brand}\n          actions={<>\n            <div className=\"ds-appshell__actions\">{actions?.(\"topnav\")}</div>\n            <Button\n              variant=\"simple\"\n              size=\"lg\"\n              isIconOnly\n              iconStart=\"menu\"\n              className=\"ds-appshell__toggle\"\n              aria-label=\"Open navigation\"\n              aria-expanded={isOpen}\n              aria-controls={drawerId}\n              onClick={() => setOpen(true)}\n            />\n          </>}\n        />\n        <div className=\"ds-appshell__body\">\n          <SideNav ref={desktopNavRef} className=\"ds-appshell__desktop-nav\" label={navigationLabel}>\n            {navigation}\n          </SideNav>\n          <main ref={mainRef} className=\"ds-appshell__main\" tabIndex={-1}>{children}</main>\n        </div>\n      </div>\n      <Drawer\n        id={drawerId}\n        isOpen={isOpen}\n        onClose={() => setOpen(false)}\n        variant=\"navigation\"\n        portalContainer={shell}\n        title={brand}\n        aria-label=\"Navigation\"\n        closeLabel=\"Close navigation\"\n        footer={drawerActions ? <SideNavFooter>{drawerActions}</SideNavFooter> : undefined}\n      >\n        <SideNav\n          className=\"ds-appshell__mobile-nav\"\n          label={navigationLabel}\n          onClick={(event) => {\n            const link = event.target instanceof Element ? event.target.closest<HTMLAnchorElement>(\"a[href]\") : null;\n            // Opening a link elsewhere (modifier keys, another button, a new tab) leaves this page in place.\n            const opensElsewhere = event.button !== 0 || event.metaKey || event.ctrlKey || event.shiftKey\n              || event.altKey || link?.target === \"_blank\";\n            if (link && !opensElsewhere) setOpen(false);\n          }}\n        >\n          {navigation}\n        </SideNav>\n      </Drawer>\n    </div>\n  );\n});\n"],"mappings":"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"}