@jskit-ai/agent-docs 0.1.116 → 0.1.118

package/guide/agent/app-setup/a-more-interesting-shell.md

@@ -675,6 +675,21 @@ The closed presentation is adaptive and uses Vuetify's Material navigation
 components. On compact/mobile layouts the temporary drawer closes completely.
 On medium and expanded layouts it collapses to a navigation rail by default,
 so primary navigation remains visible. Opening it restores the full drawer.
+Escape and outside dismissal close only the compact temporary drawer and return
+focus to the shell navigation toggle. They do not collapse permanent desktop
+navigation.
+
+The open drawer is content-aware by default. After the visible semantic
+placements and fonts settle, `ShellLayout` measures the rendered labels and
+uses one `navigationItemSpacing` value for the icon-to-label gap and the space
+between the widest label and the drawer edge. It defaults to 12 CSS pixels and
+can be set from 8–24px. The shell remeasures when placements, localization,
+fonts, spacing, the active surface, or the window layout change, and clamps
+unusually long labels to a safe range. The
+closed desktop rail remains 80 CSS pixels wide by default, with every icon and
+its Material selected-state indicator centred in the rail. Rail tooltips use
+one explicit opaque theme color pair and open on pointer hover or keyboard
+focus.
 
 The app-owned `ShellLayout` can opt into a fully hidden wide drawer when the
 product has another discoverable navigation affordance:
@@ -688,6 +703,23 @@ product has another discoverable navigation affordance:
 The default is `desktop-drawer-closed-mode="rail"`. Prefer that Material 3
 pattern; do not imitate a rail with custom CSS or a second menu registry.
 
+Applications that need product-specific dimensions or spacing can use the
+public props instead of overriding Vuetify drawer CSS:
+
+```vue
+<ShellLayout :drawer-width="280" :rail-width="64" :navigation-item-spacing="12">
+  <RouterView />
+</ShellLayout>
+```
+
+Omit `drawer-width` to retain content-aware sizing. Omit `rail-width` to retain
+the 80px Material navigation-rail default. Drawer overrides are clamped to
+120–360px and rail overrides to 48–160px so shell navigation cannot consume an
+unsafe share of the viewport or shrink below its touch targets. The app-owned
+`src/components/ShellLayout.vue` wrapper also forwards
+`navigation-item-spacing`, so an application does not need to copy or restyle
+the drawer implementation.
+
 `useShellErrorPresentationStore()` exposes the current banner, snackbar, and dialog presentation state behind `ShellErrorHost`.
 
 The simplest direct store usage looks like this:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jskit-ai/agent-docs",
-  "version": "0.1.116",
+  "version": "0.1.118",
   "description": "Distributed JSKIT agent references, prompts, guides, and generated reference maps.",
   "type": "module",
   "files": [

package/patterns/placements.md

@@ -58,6 +58,9 @@ Runtime behavior:
 - Runtime resolves the component token as `entry.componentToken || variant.renderers[entry.kind]`.
 - Entries without a resolvable component token do not render.
 - `when()` receives placement context including `app`, `surface`, `target`, `layoutClass`, runtime context, local outlet context, and context contributors.
+- The standard `ShellLayout` uses one `navigationItemSpacing` value (12px by default) for the icon-to-label gap and the widest label's logical-end gap. It remeasures its content-aware width after placement, locale, font, surface, spacing, and layout changes. Use `drawerWidth` only when a product needs a fixed width; do not add consumer `.v-navigation-drawer` overrides.
+- On medium and expanded layouts, closing the standard drawer produces an 80px Material navigation rail by default. Use `railWidth` to configure that width, or `desktopDrawerClosedMode="hidden"` only when another discoverable navigation surface exists.
+- The shell link renderers own rail centring, selected-state treatment, and opaque theme-aware tooltips. Applications should keep supplying the same semantic placement records rather than creating rail-only links or tooltip CSS.
 
 CLI and generators:
 

package/patterns/ui-testing.md

@@ -13,6 +13,7 @@ Rules:
 - Generator or package template UI changes must be checked at compact phone, tablet-ish medium, and expanded desktop widths.
 - For generated UI, check horizontal overflow, clipped or invisible text, duplicate navigation, and broken route placement at every standard viewport. On compact screens, also check generated-screen tap targets under 48 px; medium and expanded layouts may use their documented denser controls.
 - Apps with `shell-web` installed should start from `tests/e2e/adaptive-shell.spec.ts` and extend it with feature-specific assertions.
+- The package helper reads the shell's rendered `data-layout` contract, waits for drawer transitions without fixed sleeps, verifies compact Escape/outside dismissal, checks content-aware drawer fit, and measures rail icon centring against the configured width. Do not replace it with viewport-name assumptions or immediate animation-time geometry reads.
 - Generated `playwright.config.mjs` delegates to `@jskit-ai/jskit-cli/test/playwright`. Do not copy base-URL, web-server, or storage-state logic into app tests.
 - Use relative paths such as `page.goto("/home")`. The shared config owns the browser base URL.
 - A managed runner supplies `PLAYWRIGHT_BASE_URL`. When it is set, JSKIT does not start another app server.

package/reference/autogen/packages/shell-web.md

@@ -65,6 +65,17 @@ Local functions
 Exports
 - None
 Local functions
+- `attachShellListeners()`
+- `detachShellListeners()`
+- `handleDrawerOpenChange(open)`
+- `handleLayoutClassChange(compact)`
+- `handleShellKeydown(event)`
+- `focusNavigationToggle()`
+- `initializeDrawerMeasurement()`
+- `resolveNavigationDrawerElement()`
+- `scheduleDrawerWidthMeasurement()`
+- `measureDrawerContentWidth()`
+- `measureRenderedText(element)`
 - `handlePullPointerDown(event)`
 - `handleDrawerVisibilityChange(open)`
 - `handlePullPointerMove(event)`
@@ -91,6 +102,10 @@ Local functions
 Exports
 - None
 
+### `src/client/components/ShellNavigationTooltip.vue`
+Exports
+- None
+
 ### `src/client/components/ShellOutlet.vue`
 Exports
 - None
@@ -412,6 +427,20 @@ Exports
 - `resolveShellDrawerPresentation({ compact = false, open = false, desktopClosedMode = "rail" } = {})`
 - `resolveShellDrawerToggleLabel({ compact = false, open = false } = {})`
 
+### `src/client/support/drawerWidth.js`
+Exports
+- `DEFAULT_SHELL_DRAWER_WIDTH`
+- `DEFAULT_SHELL_NAVIGATION_ITEM_SPACING`
+- `DEFAULT_SHELL_RAIL_WIDTH`
+- `MAXIMUM_SHELL_DRAWER_WIDTH`
+- `MINIMUM_SHELL_DRAWER_WIDTH`
+- `normalizeShellDrawerWidth(value, fallback = DEFAULT_SHELL_DRAWER_WIDTH)`
+- `normalizeShellNavigationItemSpacing(value, fallback = DEFAULT_SHELL_NAVIGATION_ITEM_SPACING)`
+- `normalizeShellRailWidth(value, fallback = DEFAULT_SHELL_RAIL_WIDTH)`
+- `resolveContentAwareDrawerWidth(measurements = [], { endGap = DEFAULT_SHELL_NAVIGATION_ITEM_SPACING, minimum = MINIMUM_SHELL_DRAWER_WIDTH, maximum = MAXIMUM_SHELL_DRAWER_WIDTH, fallback = DEFAULT_SHELL_DRAWER_WIDTH } = {})`
+Local functions
+- `clampNumber(value, minimum, maximum)`
+
 ### `src/client/support/menuLinkTarget.js`
 Exports
 - `normalizeMenuLinkPathname(pathname = "")`
@@ -422,6 +451,10 @@ Local functions
 - `isRelativeMenuLinkTarget(target = "")`
 - `surfaceRequiresWorkspaceFromPlacementContext(contextValue = null, surfaceId = "")`
 
+### `src/client/support/navigationLinkKeyboard.js`
+Exports
+- `activateShellNavigationLinkOnSpace(event)`
+
 ### `src/client/support/routeTransitionKey.js`
 Exports
 - `resolveShellRouteTransitionKey({ routePathKey = "", routeTransitionName = "", surfaceId = "" } = {})`
@@ -512,3 +545,24 @@ Exports
 ### `package.descriptor.mjs`
 Exports
 - None
+
+### fixtures
+
+### `fixtures/adaptive-shell/src/App.vue`
+Exports
+- None
+
+### `fixtures/adaptive-shell/src/main.js`
+Exports
+- None
+Local functions
+- `createSurfacePlacement(surface, order, label, suffix)`
+- `createSurfacePlacements(surface)`
+
+### `fixtures/adaptive-shell/src/ScreenPage.vue`
+Exports
+- None
+
+### `fixtures/adaptive-shell/vite.config.mjs`
+Exports
+- None

package/skills/jskit/references/ui-operations.md

@@ -47,6 +47,12 @@ navigation as a rail. Use `desktopDrawerClosedMode="hidden"` only when another
 discoverable navigation affordance exists. Do not create a second drawer/menu
 registry or imitate the rail with CSS.
 
+The drawer uses `navigationItemSpacing` (12px) for icon/label and widest-label/
+edge gaps. Its 80px rail centres complete 48px targets and theme-owned
+tooltips. Set `railWidth` (for example, `64`) for another density, or
+`drawerWidth` for a fixed open width. The app wrapper forwards all three; never
+override `.v-navigation-drawer` in an app.
+
 ## Browser verification
 
 Exercise user-facing changes with Playwright at compact, medium, and expanded