@jskit-ai/agent-docs 0.1.149 → 0.1.151

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

@@ -0,0 +1,80 @@
+<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">
+    <div class="home-surface-screen__actions">
+      <v-btn color="primary" variant="flat" to="/home/settings/general">Settings</v-btn>
+    </div>
+
+    <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-panel-padding: 1rem;
+}
+
+.home-surface-screen__actions {
+  display: flex;
+  justify-content: flex-end;
+}
+
+.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__actions :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,37 @@
+<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">
+    <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>
+
+    <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,90 @@
+<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">
+    <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-panel-padding: 1rem;
+}
+
+.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__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,77 @@
+---
+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.
+- Route pages do not add a page header or standalone heading by default.
+- 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,7 @@
+<template>
+  <section>
+    <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,7 @@
+<template>
+  <section>
+    <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,25 @@
+<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">
+    <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>

package/skills/jskit/references/patterns/ui/page-and-placement/example/src/placement.js

@@ -0,0 +1,52 @@
+import { createPlacementRegistry } from "@jskit-ai/shell-web/client/placement";
+
+const registry = createPlacementRegistry();
+const { addPlacement } = registry;
+
+addPlacement({
+  id: "catalogue.reports.link",
+  target: "shell.primary-nav",
+  kind: "link",
+  surfaces: ["home"],
+  order: 120,
+  props: {
+    label: "Reports",
+    icon: "mdi-chart-box-outline",
+    surface: "home",
+    scopedSuffix: "/reports",
+    unscopedSuffix: "/reports"
+  }
+});
+
+for (const [id, label, suffix, order] of [
+  ["overview", "Overview", "/reports/overview", 100],
+  ["activity", "Activity", "/reports/activity", 110]
+]) {
+  addPlacement({
+    id: `catalogue.reports.${id}.link`,
+    target: "page.section-nav",
+    owner: "reports",
+    kind: "link",
+    surfaces: ["home"],
+    order,
+    props: {
+      label,
+      surface: "home",
+      scopedSuffix: suffix,
+      unscopedSuffix: suffix
+    }
+  });
+}
+
+addPlacement({
+  id: "catalogue.sync-status",
+  target: "shell.status",
+  kind: "component",
+  surfaces: ["home"],
+  order: 100,
+  componentToken: "local.main.ui.sync-status"
+});
+
+export default function getPlacements() {
+  return registry.build();
+}