@jskit-ai/agent-docs 0.1.149 → 0.1.150

package/skills/jskit/references/patterns/shell/application-shell/example/src/error.js

@@ -0,0 +1,19 @@
+import { createDefaultErrorPolicy } from "@jskit-ai/shell-web/client/error";
+
+/**
+ * App-owned error handling contract.
+ * - intent chooses default presentation: resource-load, action-feedback, app-recoverable, blocking.
+ * - policy(event, ctx): decide channel + presenter + message.
+ * - defaultPresenterId: used when policy does not set presenterId.
+ * - presenters: optional custom presenters registered at boot.
+ */
+export default Object.freeze({
+  defaultPresenterId: "material.snackbar",
+  policy: createDefaultErrorPolicy({
+    resourceLoadChannel: "silent",
+    actionFeedbackChannel: "snackbar",
+    appRecoverableChannel: "banner",
+    blockingChannel: "dialog"
+  }),
+  presenters: []
+});

package/skills/jskit/references/patterns/shell/application-shell/example/src/pages/home/index.vue

@@ -0,0 +1,106 @@
+<script setup>
+import { computed } from "vue";
+import { useQuery } from "@tanstack/vue-query";
+
+const healthQuery = useQuery({
+  queryKey: ["shell-web", "health"],
+  queryFn: async () => {
+    const response = await fetch("/api/health");
+    if (!response.ok) {
+      throw new Error("Health request failed.");
+    }
+    return response.json();
+  },
+  refetchOnWindowFocus: false
+});
+
+const health = computed(() => {
+  if (healthQuery.isPending.value || healthQuery.isFetching.value) {
+    return "loading...";
+  }
+
+  if (healthQuery.error.value) {
+    return "unreachable";
+  }
+
+  return healthQuery.data.value?.ok ? "ok" : "unhealthy";
+});
+</script>
+
+<template>
+  <section class="home-surface-screen d-flex flex-column ga-4">
+    <header class="home-surface-screen__header">
+      <div>
+        <p class="text-overline text-medium-emphasis mb-1">Home</p>
+        <h1 class="home-surface-screen__title">Ready</h1>
+        <p class="text-body-2 text-medium-emphasis mb-0">
+          Core services are available.
+        </p>
+      </div>
+      <v-btn color="primary" variant="flat" to="/home/settings/general">Settings</v-btn>
+    </header>
+
+    <v-sheet rounded="lg" border class="home-surface-screen__panel">
+      <div class="home-surface-screen__status">
+        <span class="text-caption text-medium-emphasis">Service health</span>
+        <strong>{{ health }}</strong>
+      </div>
+      <v-divider vertical class="d-none d-sm-block" />
+      <div class="home-surface-screen__status">
+        <span class="text-caption text-medium-emphasis">Route</span>
+        <strong>/home</strong>
+      </div>
+    </v-sheet>
+  </section>
+</template>
+
+<style scoped>
+.home-surface-screen {
+  --home-surface-title-size: 2rem;
+  --home-surface-panel-padding: 1rem;
+}
+
+.home-surface-screen__header {
+  align-items: flex-start;
+  display: flex;
+  gap: 1rem;
+  justify-content: space-between;
+}
+
+.home-surface-screen__title {
+  font-size: var(--home-surface-title-size);
+  font-weight: 700;
+  letter-spacing: 0;
+  line-height: 1.1;
+  margin: 0 0 0.4rem;
+}
+
+.home-surface-screen__panel {
+  align-items: stretch;
+  display: flex;
+  flex-wrap: wrap;
+  gap: 1rem;
+  padding: var(--home-surface-panel-padding);
+}
+
+.home-surface-screen__status {
+  display: grid;
+  gap: 0.15rem;
+  min-width: 9rem;
+}
+
+@media (max-width: 640px) {
+  .home-surface-screen {
+    --home-surface-title-size: 1.5rem;
+  }
+
+  .home-surface-screen__header {
+    flex-direction: column;
+  }
+
+  .home-surface-screen__header :deep(.v-btn) {
+    min-height: 48px;
+    width: 100%;
+  }
+}
+</style>

package/skills/jskit/references/patterns/shell/application-shell/example/src/pages/home/settings/general/index.vue

@@ -0,0 +1,40 @@
+<script setup>
+import { computed } from "vue";
+import { useShellLayoutState } from "@jskit-ai/shell-web/client/composables/useShellLayoutState";
+
+const { drawerDefaultOpen, setDrawerDefaultOpen } = useShellLayoutState();
+
+const drawerDefaultOpenModel = computed({
+  get() {
+    return drawerDefaultOpen.value;
+  },
+  set(value) {
+    setDrawerDefaultOpen(Boolean(value));
+  }
+});
+</script>
+
+<template>
+  <section class="settings-general-screen d-flex flex-column ga-4">
+    <div>
+      <h2 class="text-h6 mb-2">Navigation</h2>
+      <p class="text-body-2 text-medium-emphasis mb-0">
+        On wider screens, collapsed navigation remains available as a rail. Phone layouts close the drawer and keep primary navigation in the bottom bar.
+      </p>
+    </div>
+
+    <v-switch
+      v-model="drawerDefaultOpenModel"
+      color="primary"
+      inset
+      hide-details="auto"
+      label="Start with expanded navigation on wider screens"
+    />
+  </section>
+</template>
+
+<style scoped>
+.settings-general-screen :deep(.v-switch) {
+  min-height: 48px;
+}
+</style>

package/skills/jskit/references/patterns/shell/application-shell/example/src/pages/home/settings/index.vue

@@ -0,0 +1,7 @@
+<script setup>
+import { redirectToChild } from "@jskit-ai/kernel/client/pageRedirects";
+
+definePage({
+  redirect: redirectToChild("general")
+});
+</script>

package/skills/jskit/references/patterns/shell/application-shell/example/src/pages/home/settings.vue

@@ -0,0 +1,109 @@
+<script setup>
+import ShellOutlet from "@jskit-ai/shell-web/client/components/ShellOutlet";
+import { RouterView } from "vue-router";
+</script>
+
+<template>
+  <section class="settings-shell d-flex flex-column ga-4">
+    <header>
+      <p class="text-overline text-medium-emphasis mb-1">Settings</p>
+      <h1 class="settings-shell__title">Home settings</h1>
+      <p class="text-body-2 text-medium-emphasis mb-0">Configure shell behavior for this surface.</p>
+    </header>
+
+    <v-sheet rounded="lg" border class="settings-shell__panel">
+      <div class="settings-shell__body">
+        <nav class="settings-shell__nav" aria-label="Home settings sections">
+          <v-list nav density="compact" rounded="lg">
+            <ShellOutlet target="home-settings:primary-menu" />
+          </v-list>
+        </nav>
+
+        <main class="settings-shell__content">
+          <RouterView />
+        </main>
+      </div>
+    </v-sheet>
+  </section>
+</template>
+
+<style scoped>
+.settings-shell {
+  --settings-shell-title-size: 1.85rem;
+  --settings-shell-panel-padding: 1rem;
+}
+
+.settings-shell__title {
+  font-size: var(--settings-shell-title-size);
+  font-weight: 650;
+  letter-spacing: 0;
+  line-height: 1.15;
+  margin: 0 0 0.35rem;
+}
+
+.settings-shell__panel {
+  overflow: hidden;
+}
+
+.settings-shell__body {
+  display: grid;
+  gap: 1rem;
+  grid-template-columns: minmax(12rem, 16rem) minmax(0, 1fr);
+  padding: var(--settings-shell-panel-padding);
+}
+
+.settings-shell__content {
+  border-left: 1px solid rgba(var(--v-theme-on-surface), 0.18);
+  min-width: 0;
+  padding-left: 1rem;
+}
+
+.settings-shell__nav :deep(.v-list) {
+  padding: 0.35rem;
+}
+
+.settings-shell__nav :deep(.v-list-item) {
+  min-height: 48px;
+  padding-inline: 0.6rem 0.7rem;
+}
+
+.settings-shell__nav :deep(.v-list-item__prepend) {
+  margin-inline-end: 0;
+}
+
+.settings-shell__nav :deep(.v-list-item__spacer) {
+  min-width: 0.5rem;
+  width: 0.5rem;
+}
+
+.settings-shell__nav :deep(.v-list-item-title) {
+  line-height: 1.2;
+}
+
+@media (max-width: 960px) {
+  .settings-shell {
+    --settings-shell-title-size: 1.35rem;
+  }
+
+  .settings-shell__body {
+    grid-template-columns: 1fr;
+  }
+
+  .settings-shell__nav :deep(.v-list) {
+    display: flex;
+    gap: 0.25rem;
+    overflow-x: auto;
+    scrollbar-width: thin;
+  }
+
+  .settings-shell__nav :deep(.v-list-item) {
+    flex: 0 0 auto;
+    min-height: 48px;
+  }
+
+  .settings-shell__content {
+    border-left: 0;
+    padding-left: 0;
+  }
+}
+</style>

package/skills/jskit/references/patterns/shell/application-shell/example/src/pages/home.vue

@@ -0,0 +1,20 @@
+<route lang="json">
+{
+  "meta": {
+    "jskit": {
+      "surface": "home"
+    }
+  }
+}
+</route>
+
+<script setup>
+import ShellLayout from "@/components/ShellLayout.vue";
+import { RouterView } from "vue-router";
+</script>
+
+<template>
+  <ShellLayout title="" subtitle="">
+    <RouterView />
+  </ShellLayout>
+</template>

package/skills/jskit/references/patterns/shell/application-shell/example/src/placement.js

@@ -0,0 +1,56 @@
+import { createPlacementRegistry } from "@jskit-ai/shell-web/client/placement";
+
+const registry = createPlacementRegistry();
+const { addPlacement } = registry;
+
+export { addPlacement };
+
+// Keep the default export near the top so module installers can append addPlacement(...)
+// blocks at the bottom of this file without changing the export section.
+export default function getPlacements() {
+  return registry.build();
+}
+
+addPlacement({
+  id: "shell-web.home.menu.home",
+  target: "shell.primary-nav",
+  kind: "link",
+  surfaces: ["home"],
+  order: 50,
+  props: {
+    label: "Home",
+    surface: "home",
+    scopedSuffix: "/",
+    unscopedSuffix: "/",
+    exact: true
+  }
+});
+
+addPlacement({
+  id: "shell-web.home.menu.settings",
+  target: "shell.primary-nav",
+  kind: "link",
+  surfaces: ["home"],
+  order: 100,
+  props: {
+    label: "Settings",
+    surface: "home",
+    scopedSuffix: "/settings",
+    unscopedSuffix: "/settings"
+  }
+});
+
+addPlacement({
+  id: "shell-web.home.settings.general",
+  target: "page.section-nav",
+  owner: "home-settings",
+  kind: "link",
+  surfaces: ["home"],
+  order: 100,
+  props: {
+    label: "General",
+    surface: "home",
+    scopedSuffix: "/settings/general",
+    unscopedSuffix: "/settings/general"
+  }
+});

package/skills/jskit/references/patterns/shell/application-shell/example/src/placementTopology.js

@@ -0,0 +1,149 @@
+const placements = [];
+
+function addPlacementTopology(value = {}) {
+  placements.push(value);
+}
+
+export { addPlacementTopology };
+export default { placements };
+
+const menuLinkRenderers = Object.freeze({
+  link: "local.main.ui.surface-aware-menu-link-item"
+});
+
+const bottomNavLinkRenderers = Object.freeze({
+  link: "local.main.ui.tab-link-item"
+});
+
+addPlacementTopology({
+  id: "shell.primary-nav",
+  description: "Primary top-level navigation for the current surface.",
+  surfaces: ["*"],
+  default: true,
+  variants: {
+    compact: {
+      outlet: "shell-layout:primary-bottom-nav",
+      renderers: bottomNavLinkRenderers
+    },
+    medium: {
+      outlet: "shell-layout:primary-menu",
+      renderers: menuLinkRenderers
+    },
+    expanded: {
+      outlet: "shell-layout:primary-menu",
+      renderers: menuLinkRenderers
+    }
+  }
+});
+
+addPlacementTopology({
+  id: "shell.secondary-nav",
+  description: "Secondary navigation for the current surface.",
+  surfaces: ["*"],
+  variants: {
+    compact: {
+      outlet: "shell-layout:secondary-menu",
+      renderers: menuLinkRenderers
+    },
+    medium: {
+      outlet: "shell-layout:secondary-menu",
+      renderers: menuLinkRenderers
+    },
+    expanded: {
+      outlet: "shell-layout:secondary-menu",
+      renderers: menuLinkRenderers
+    }
+  }
+});
+
+addPlacementTopology({
+  id: "shell.identity",
+  description: "Current surface identity and switcher controls.",
+  surfaces: ["*"],
+  variants: {
+    compact: {
+      outlet: "shell-layout:top-left"
+    },
+    medium: {
+      outlet: "shell-layout:top-left"
+    },
+    expanded: {
+      outlet: "shell-layout:top-left"
+    }
+  }
+});
+
+addPlacementTopology({
+  id: "shell.status",
+  description: "Surface status, connection, and utility indicators.",
+  surfaces: ["*"],
+  variants: {
+    compact: {
+      outlet: "shell-layout:top-right"
+    },
+    medium: {
+      outlet: "shell-layout:top-right"
+    },
+    expanded: {
+      outlet: "shell-layout:top-right"
+    }
+  }
+});
+
+addPlacementTopology({
+  id: "shell.global-actions",
+  description: "Global surface actions that should stay outside primary navigation.",
+  surfaces: ["*"],
+  variants: {
+    compact: {
+      outlet: "shell-layout:top-right",
+      renderers: menuLinkRenderers
+    },
+    medium: {
+      outlet: "shell-layout:top-right",
+      renderers: menuLinkRenderers
+    },
+    expanded: {
+      outlet: "shell-layout:top-right",
+      renderers: menuLinkRenderers
+    }
+  }
+});
+
+addPlacementTopology({
+  id: "page.supporting-content",
+  description: "Supporting page content that opens as a bottom sheet on compact layouts and a side panel on wider layouts.",
+  surfaces: ["*"],
+  variants: {
+    compact: {
+      outlet: "shell-layout:supporting-bottom-sheet"
+    },
+    medium: {
+      outlet: "shell-layout:supporting-side-panel"
+    },
+    expanded: {
+      outlet: "shell-layout:supporting-side-panel"
+    }
+  }
+});
+
+addPlacementTopology({
+  id: "page.section-nav",
+  owner: "home-settings",
+  description: "Navigation between child pages in the home settings section.",
+  surfaces: ["home"],
+  variants: {
+    compact: {
+      outlet: "home-settings:primary-menu",
+      renderers: menuLinkRenderers
+    },
+    medium: {
+      outlet: "home-settings:primary-menu",
+      renderers: menuLinkRenderers
+    },
+    expanded: {
+      outlet: "home-settings:primary-menu",
+      renderers: menuLinkRenderers
+    }
+  }
+});

package/skills/jskit/references/patterns/shell/application-shell/example/tests/e2e/adaptive-shell.spec.ts

@@ -0,0 +1,10 @@
+import { expect, test } from "@playwright/test";
+import { DEFAULT_VIEWPORTS, runAdaptiveShellSmokeCase } from "@jskit-ai/shell-web/test/adaptiveShellSmoke";
+
+test.describe("generated adaptive shell smoke", () => {
+  for (const viewport of DEFAULT_VIEWPORTS) {
+    test(`${viewport.name} layout has reachable navigation and no horizontal overflow`, async ({ page }) => {
+      await runAdaptiveShellSmokeCase({ page, expect, viewport });
+    });
+  }
+});

package/skills/jskit/references/patterns/ui/page-and-placement/PATTERN.md

@@ -0,0 +1,76 @@
+---
+id: ui/page-and-placement
+title: Routed page, section navigation, and placed element
+summary: Add product routes and shell extensions through file routing, semantic placements, topology, and registered component tokens.
+keywords: component, navigation, outlet, page, placement, routes, section, shell, subpages, vue
+requires: @jskit-ai/kernel, @jskit-ai/shell-web
+---
+
+# Routed page, section navigation, and placed element
+
+## Use when
+
+Use this pattern for an application-owned route page, a section with child
+routes, or a component rendered in an existing shell placement. It demonstrates
+the same public contracts for all three without a page generator.
+
+## Do not use when
+
+Do not use section navigation for a single page, add a primary link for a detail
+or workflow route, or create a new placement system when an existing semantic
+placement fits. CRUD routes should use the CRUD screen pattern.
+
+## Product decisions
+
+Decide the route, surface, navigation role, label, icon, section ownership,
+ordering, and whether the content belongs in navigation or a component outlet.
+These are product information architecture decisions, not defaults to infer from
+a filename alone.
+
+## Invariants
+
+- File routes and placement destinations agree.
+- Placement ids describe product ownership, not the authoring mechanism.
+- Child links share an explicit section owner.
+- Topology maps each semantic placement to concrete responsive outlets.
+- Placed components are registered by token through a client provider.
+- Compact navigation controls remain accessible and at least 48 CSS pixels.
+- Application source has no generated-file marker, receipt, or overwrite state.
+
+## Framework APIs
+
+Use `createPlacementRegistry()`, `addPlacement()`, `addPlacementTopology()`, and
+`ShellOutlet` from `@jskit-ai/shell-web`. Use file routes and
+`redirectToChild()` from `@jskit-ai/kernel`. Register app-owned component tokens
+through the application's normal client provider.
+
+## Example files
+
+`example/` contains a Reports section with Overview and Activity child routes,
+the matching section-navigation placements/topology, and a Sync Status component
+placed in the existing shell status area.
+
+## Variation points
+
+Change the route hierarchy, surface, semantic target, section owner, component
+token, order, label, icon, and responsive outlet mapping. Omit the parent host
+and topology when no child navigation is needed. Omit provider registration for
+link-only placements.
+
+## Verification
+
+- navigate directly to each route and through each visible link
+- verify the section index redirects to its intended child
+- verify the placed component resolves through its provider token
+- exercise compact, medium, and expanded variants
+- verify current-link state, keyboard operation, target size, and no overflow
+- run client tests and the production build
+
+## Avoid
+
+- generator-branded placement ids or CSS classes
+- navigation links for detail/workflow routes unless explicitly chosen
+- duplicated route tables beside file routing
+- hard-coded component instances where a semantic placement is required
+- placeholder pages that instruct developers to replace their content
+- provenance comments, receipts, or hidden mutation markers

package/skills/jskit/references/patterns/ui/page-and-placement/example/packages/main/src/client/providers/MainClientProvider.js

@@ -0,0 +1,14 @@
+import { defineProvider } from "@jskit-ai/kernel/shared/capabilities";
+import SyncStatusElement from "/src/components/SyncStatusElement.vue";
+
+const MainClientProvider = defineProvider({
+  id: "local.main.client",
+  requires: {
+    components: "client.components"
+  },
+  setup({ components }) {
+    components.register("local.main.ui.sync-status", SyncStatusElement);
+  }
+});
+
+export { MainClientProvider };

package/skills/jskit/references/patterns/ui/page-and-placement/example/src/components/SyncStatusElement.vue

@@ -0,0 +1,16 @@
+<template>
+  <div class="sync-status" role="status" aria-label="Catalogue synchronized">
+    <v-icon icon="mdi-cloud-check-outline" size="small" aria-hidden="true" />
+    <span class="text-body-2">Synced</span>
+  </div>
+</template>
+
+<style scoped>
+.sync-status {
+  align-items: center;
+  display: inline-flex;
+  gap: 0.5rem;
+  min-height: 48px;
+  min-width: 0;
+}
+</style>

package/skills/jskit/references/patterns/ui/page-and-placement/example/src/pages/home/reports/activity.vue

@@ -0,0 +1,8 @@
+<template>
+  <section aria-labelledby="reports-activity-title">
+    <h2 id="reports-activity-title" class="text-h5 mb-2">Activity</h2>
+    <p class="text-body-1 text-medium-emphasis mb-0">
+      Recent catalogue changes appear here.
+    </p>
+  </section>
+</template>

package/skills/jskit/references/patterns/ui/page-and-placement/example/src/pages/home/reports/index.vue

@@ -0,0 +1,7 @@
+<script setup>
+import { redirectToChild } from "@jskit-ai/kernel/client/pageRedirects";
+
+definePage({
+  redirect: redirectToChild("overview")
+});
+</script>

package/skills/jskit/references/patterns/ui/page-and-placement/example/src/pages/home/reports/overview.vue

@@ -0,0 +1,8 @@
+<template>
+  <section aria-labelledby="reports-overview-title">
+    <h2 id="reports-overview-title" class="text-h5 mb-2">Overview</h2>
+    <p class="text-body-1 text-medium-emphasis mb-0">
+      Your reading and catalogue summary appears here.
+    </p>
+  </section>
+</template>

package/skills/jskit/references/patterns/ui/page-and-placement/example/src/pages/home/reports.vue

@@ -0,0 +1,33 @@
+<script setup>
+import ShellOutlet from "@jskit-ai/shell-web/client/components/ShellOutlet";
+import { RouterView } from "vue-router";
+</script>
+
+<template>
+  <section class="reports-section d-flex flex-column ga-4">
+    <header>
+      <p class="text-overline text-medium-emphasis mb-1">Insights</p>
+      <h1 class="text-h4 font-weight-medium mb-1">Reports</h1>
+      <p class="text-body-2 text-medium-emphasis mb-0">
+        Review catalogue activity and completion trends.
+      </p>
+    </header>
+
+    <nav aria-label="Report sections">
+      <v-tabs density="comfortable">
+        <ShellOutlet target="reports:section-nav" />
+      </v-tabs>
+    </nav>
+
+    <main class="reports-section__content">
+      <RouterView />
+    </main>
+  </section>
+</template>
+
+<style scoped>
+.reports-section,
+.reports-section__content {
+  min-width: 0;
+}
+</style>