@jskit-ai/agent-docs 0.1.149 → 0.1.150

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();
+}

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

@@ -0,0 +1,29 @@
+const placements = [];
+
+function addPlacementTopology(value = {}) {
+  placements.push(value);
+}
+
+addPlacementTopology({
+  id: "page.section-nav",
+  owner: "reports",
+  description: "Navigation between report pages.",
+  surfaces: ["home"],
+  variants: {
+    compact: {
+      outlet: "reports:section-nav",
+      renderers: { link: "local.main.ui.tab-link-item" }
+    },
+    medium: {
+      outlet: "reports:section-nav",
+      renderers: { link: "local.main.ui.tab-link-item" }
+    },
+    expanded: {
+      outlet: "reports:section-nav",
+      renderers: { link: "local.main.ui.tab-link-item" }
+    }
+  }
+});
+
+export { addPlacementTopology };
+export default { placements };

package/skills/jskit/references/patterns/users/account-settings/PATTERN.md

@@ -0,0 +1,61 @@
+---
+id: users/account-settings
+title: Account settings surface
+summary: Compose an account settings route and profile, preference, and notification sections from JSKIT user web components.
+keywords: account, notifications, preferences, profile, settings, user, vue
+requires: @jskit-ai/users-core, @jskit-ai/users-web, @jskit-ai/shell-web
+---
+
+# Account settings surface
+
+## Use when
+
+Use this pattern when authenticated users need to manage their own profile and
+account preferences.
+
+## Do not use when
+
+Do not use this pattern for administrator-managed users, authentication
+credential storage, or anonymous profile editing.
+
+## Product decisions
+
+Choose editable profile fields, preference vocabulary, notification options,
+section order, and which account operations require reauthentication.
+
+## Framework APIs
+
+Use account settings elements and composables from `@jskit-ai/users-web`,
+ordinary `useCommand()` mutation behavior, and JSKIT shell placements.
+
+## Invariants
+
+- Sections use JSKIT account settings APIs rather than direct HTTP helpers.
+- Cached resource data hydrates local writable fields immediately.
+- Mutation errors use the standard toast and do not push the form down.
+- Loading uses layout-stable skeletons, never an indeterminate spinner.
+- Pending controls keep stable labels and prevent duplicate submission.
+- The route and placement owner agree.
+
+## Example files
+
+`example/` contains an account route and three concrete settings sections.
+Adapt their fields and copy while retaining the shared account runtime.
+
+## Variation points
+
+Change sections, fields, copy, order, permissions, preference choices, and
+notification vocabulary while keeping server-owned validation authoritative.
+
+## Verification
+
+Navigate away and back with warm cache, exercise browser back/forward, save and
+clear fields, verify toast errors, inspect skeleton geometry, and test keyboard
+operation at compact and expanded widths.
+
+## Avoid
+
+- page-local request clients
+- inline mutation alerts that shift content
+- lazy non-immediate watchers for initial hydration
+- copied user repositories or generator source markers

package/skills/jskit/references/patterns/users/account-settings/example/src/components/account/settings/AccountSettingsNotificationsSection.vue

@@ -0,0 +1,81 @@
+<script setup>
+const props = defineProps({
+  runtime: {
+    type: Object,
+    required: true
+  }
+});
+
+const notifications = props.runtime.notifications;
+</script>
+
+<template>
+  <v-sheet rounded="lg" border class="account-settings-section">
+    <header class="account-settings-section__header">
+      <h2 class="account-settings-section__title">Notifications</h2>
+    </header>
+    <div class="account-settings-section__body">
+      <v-form @submit.prevent="notifications.submit" novalidate>
+        <v-switch
+          v-model="notifications.form.productUpdates"
+          label="Product updates"
+          color="primary"
+          hide-details
+          :disabled="notifications.isSaving.value || notifications.isRefreshing.value"
+          class="mb-2"
+        />
+        <v-switch
+          v-model="notifications.form.accountActivity"
+          label="Account activity alerts"
+          color="primary"
+          hide-details
+          :disabled="notifications.isSaving.value || notifications.isRefreshing.value"
+          class="mb-2"
+        />
+        <v-switch
+          v-model="notifications.form.securityAlerts"
+          label="Security alerts (required)"
+          color="primary"
+          hide-details
+          disabled
+          class="mb-4"
+        />
+        <v-btn
+          type="submit"
+          color="primary"
+          :loading="notifications.isSaving.value"
+          :disabled="notifications.isRefreshing.value"
+        >
+          Save notification settings
+        </v-btn>
+      </v-form>
+    </div>
+  </v-sheet>
+</template>
+
+<style scoped>
+.account-settings-section {
+  overflow: hidden;
+}
+
+.account-settings-section__header {
+  padding: 1rem 1rem 0;
+}
+
+.account-settings-section__title {
+  font-size: 1rem;
+  font-weight: 650;
+  line-height: 1.2;
+  margin: 0;
+}
+
+.account-settings-section__body {
+  padding: 1rem;
+}
+
+@media (max-width: 640px) {
+  .account-settings-section__body :deep(.v-btn) {
+    min-height: 48px;
+  }
+}
+</style>

package/skills/jskit/references/patterns/users/account-settings/example/src/components/account/settings/AccountSettingsPreferencesSection.vue

@@ -0,0 +1,151 @@
+<script setup>
+const props = defineProps({
+  runtime: {
+    type: Object,
+    required: true
+  }
+});
+
+const preferences = props.runtime.preferences;
+</script>
+
+<template>
+  <v-sheet rounded="lg" border class="account-settings-section">
+    <header class="account-settings-section__header">
+      <h2 class="account-settings-section__title">Preferences</h2>
+    </header>
+    <div class="account-settings-section__body">
+      <v-form @submit.prevent="preferences.submit" novalidate>
+        <v-row>
+          <v-col cols="12" md="4">
+            <v-select
+              v-model="preferences.form.theme"
+              label="Theme"
+              :items="preferences.options.theme"
+              item-title="title"
+              item-value="value"
+              variant="outlined"
+              density="comfortable"
+              :disabled="preferences.isSaving.value || preferences.isRefreshing.value"
+              :error-messages="preferences.fieldErrors.theme ? [preferences.fieldErrors.theme] : []"
+            />
+          </v-col>
+
+          <v-col cols="12" md="4">
+            <v-select
+              v-model="preferences.form.locale"
+              label="Language / locale"
+              :items="preferences.options.locale"
+              item-title="title"
+              item-value="value"
+              variant="outlined"
+              density="comfortable"
+              :disabled="preferences.isSaving.value || preferences.isRefreshing.value"
+              :error-messages="preferences.fieldErrors.locale ? [preferences.fieldErrors.locale] : []"
+            />
+          </v-col>
+
+          <v-col cols="12" md="4">
+            <v-select
+              v-model="preferences.form.timeZone"
+              label="Time zone"
+              :items="preferences.options.timeZone"
+              variant="outlined"
+              density="comfortable"
+              :disabled="preferences.isSaving.value || preferences.isRefreshing.value"
+              :error-messages="preferences.fieldErrors.timeZone ? [preferences.fieldErrors.timeZone] : []"
+            />
+          </v-col>
+
+          <v-col cols="12" md="4">
+            <v-select
+              v-model="preferences.form.dateFormat"
+              label="Date format"
+              :items="preferences.options.dateFormat"
+              item-title="title"
+              item-value="value"
+              variant="outlined"
+              density="comfortable"
+              :disabled="preferences.isSaving.value || preferences.isRefreshing.value"
+              :error-messages="preferences.fieldErrors.dateFormat ? [preferences.fieldErrors.dateFormat] : []"
+            />
+          </v-col>
+
+          <v-col cols="12" md="4">
+            <v-select
+              v-model="preferences.form.numberFormat"
+              label="Number format"
+              :items="preferences.options.numberFormat"
+              item-title="title"
+              item-value="value"
+              variant="outlined"
+              density="comfortable"
+              :disabled="preferences.isSaving.value || preferences.isRefreshing.value"
+              :error-messages="preferences.fieldErrors.numberFormat ? [preferences.fieldErrors.numberFormat] : []"
+            />
+          </v-col>
+
+          <v-col cols="12" md="4">
+            <v-select
+              v-model="preferences.form.currencyCode"
+              label="Currency"
+              :items="preferences.options.currency"
+              variant="outlined"
+              density="comfortable"
+              :disabled="preferences.isSaving.value || preferences.isRefreshing.value"
+              :error-messages="preferences.fieldErrors.currencyCode ? [preferences.fieldErrors.currencyCode] : []"
+            />
+          </v-col>
+
+          <v-col cols="12" md="3">
+            <v-select
+              v-model.number="preferences.form.avatarSize"
+              label="Avatar size"
+              :items="preferences.options.avatarSize"
+              variant="outlined"
+              density="comfortable"
+              :disabled="preferences.isSaving.value || preferences.isRefreshing.value"
+              :error-messages="preferences.fieldErrors.avatarSize ? [preferences.fieldErrors.avatarSize] : []"
+            />
+          </v-col>
+        </v-row>
+
+        <v-btn
+          type="submit"
+          color="primary"
+          :loading="preferences.isSaving.value"
+          :disabled="preferences.isRefreshing.value"
+        >
+          Save preferences
+        </v-btn>
+      </v-form>
+    </div>
+  </v-sheet>
+</template>
+
+<style scoped>
+.account-settings-section {
+  overflow: hidden;
+}
+
+.account-settings-section__header {
+  padding: 1rem 1rem 0;
+}
+
+.account-settings-section__title {
+  font-size: 1rem;
+  font-weight: 650;
+  line-height: 1.2;
+  margin: 0;
+}
+
+.account-settings-section__body {
+  padding: 1rem;
+}
+
+@media (max-width: 640px) {
+  .account-settings-section__body :deep(.v-btn) {
+    min-height: 48px;
+  }
+}
+</style>

package/skills/jskit/references/patterns/users/account-settings/example/src/components/account/settings/AccountSettingsProfileSection.vue

@@ -0,0 +1,120 @@
+<script setup>
+const props = defineProps({
+  runtime: {
+    type: Object,
+    required: true
+  }
+});
+
+const profile = props.runtime.profile;
+</script>
+
+<template>
+  <v-sheet rounded="lg" border class="account-settings-section">
+    <header class="account-settings-section__header">
+      <h2 class="account-settings-section__title">Profile</h2>
+    </header>
+    <div class="account-settings-section__body">
+      <v-form @submit.prevent="profile.submit" novalidate>
+        <v-row class="mb-2">
+          <v-col cols="12" md="4" class="d-flex flex-column align-center justify-center">
+            <v-avatar :size="profile.avatar.size" color="surface-variant" rounded="circle" class="mb-3">
+              <v-img v-if="profile.avatar.effectiveUrl" :src="profile.avatar.effectiveUrl" cover />
+              <span v-else class="text-h6">{{ profile.initials.value }}</span>
+            </v-avatar>
+            <div class="text-caption text-medium-emphasis">Preview size: {{ profile.avatar.size }} px</div>
+          </v-col>
+
+          <v-col cols="12" md="8">
+            <div class="d-flex flex-wrap ga-2 mb-2">
+              <v-btn
+                variant="tonal"
+                color="secondary"
+                :disabled="profile.isSaving.value || profile.isDeletingAvatar.value || profile.isRefreshing.value"
+                @click="profile.openAvatarEditor"
+              >
+                Replace avatar
+              </v-btn>
+              <v-btn
+                v-if="profile.avatar.hasUploadedAvatar"
+                variant="text"
+                color="error"
+                :loading="profile.isDeletingAvatar.value"
+                :disabled="profile.isSaving.value || profile.isRefreshing.value"
+                @click="profile.removeAvatar"
+              >
+                Remove avatar
+              </v-btn>
+            </div>
+
+            <div v-if="profile.selectedAvatarFileName.value" class="text-caption text-medium-emphasis mb-2">
+              Selected file: {{ profile.selectedAvatarFileName.value }}
+            </div>
+          </v-col>
+        </v-row>
+
+        <v-row>
+          <v-col cols="12" md="6">
+            <v-text-field
+              v-model="profile.form.displayName"
+              label="Display name"
+              variant="outlined"
+              density="comfortable"
+              autocomplete="nickname"
+              :readonly="profile.isSaving.value || profile.isRefreshing.value"
+              :error-messages="profile.fieldErrors.displayName ? [profile.fieldErrors.displayName] : []"
+            />
+          </v-col>
+
+          <v-col cols="12" md="6">
+            <v-text-field
+              v-model="profile.form.email"
+              label="Email"
+              variant="outlined"
+              density="comfortable"
+              readonly
+              hint="Managed by your sign-in account"
+              persistent-hint
+            />
+          </v-col>
+        </v-row>
+
+        <v-btn
+          type="submit"
+          color="primary"
+          :loading="profile.isSaving.value"
+          :disabled="profile.isDeletingAvatar.value || profile.isRefreshing.value"
+        >
+          Save profile
+        </v-btn>
+      </v-form>
+    </div>
+  </v-sheet>
+</template>
+
+<style scoped>
+.account-settings-section {
+  overflow: hidden;
+}
+
+.account-settings-section__header {
+  padding: 1rem 1rem 0;
+}
+
+.account-settings-section__title {
+  font-size: 1rem;
+  font-weight: 650;
+  line-height: 1.2;
+  margin: 0;
+}
+
+.account-settings-section__body {
+  padding: 1rem;
+}
+
+@media (max-width: 640px) {
+  .account-settings-section__body :deep(.v-btn) {
+    min-height: 48px;
+  }
+}
+</style>

package/skills/jskit/references/patterns/users/account-settings/example/src/pages/account/index.vue

@@ -0,0 +1,17 @@
+<route lang="json">
+{
+  "meta": {
+    "guard": {
+      "policy": "authenticated"
+    }
+  }
+}
+</route>
+
+<template>
+  <AccountSettingsClientElement />
+</template>
+
+<script setup>
+import AccountSettingsClientElement from "@jskit-ai/users-web/client/components/AccountSettingsClientElement";
+</script>

package/skills/jskit/references/patterns/users/user-administration-server/PATTERN.md

@@ -0,0 +1,64 @@
+---
+id: users/user-administration-server
+title: User administration server package
+summary: Expose user administration and workspace-scoped member operations through app-owned packages backed by JSKIT users runtime APIs.
+keywords: account, admin, member, repository, resource, routes, service, user, workspace
+requires: @jskit-ai/users-core, @jskit-ai/crud-core
+---
+
+# User administration server package
+
+## Use when
+
+Use this pattern when an application needs app-specific administration of user
+profiles or workspace members beyond the built-in account runtime.
+
+## Do not use when
+
+Do not use this pattern for self-service account settings, authentication
+credentials, or an application that needs no administrative user listing.
+
+## Product decisions
+
+Choose global versus workspace scope, visible and editable fields, permission
+policy, route surface, filters, and whether account deletion is part of the
+product. Do not expose password/session data through the resource.
+
+## Framework APIs
+
+Use `@jskit-ai/users-core` for profile persistence and policies,
+`defineCrudJsonApiFeature()` from `@jskit-ai/crud-core` for standard mechanics,
+and the resource contracts from `@jskit-ai/resource-crud-core`.
+
+## Invariants
+
+- The public user id is the resource identity.
+- Workspace operations are scoped before repository access.
+- Permission checks happen before records or record existence are disclosed.
+- Shared profile persistence remains owned by `@jskit-ai/users-core`.
+- The resource is the field contract; the feature projects its repository,
+  service, actions, and routes without app-local ceremony.
+
+## Example files
+
+`example/packages/users/` is a global administration package.
+`example/packages/users-workspace/` demonstrates the workspace route/action
+boundary while reusing the same service contract. Copy only the composition
+that matches the product and adapt it as ordinary application source.
+
+## Variation points
+
+Change scope, route surface, visible fields, filters, sorting, permission
+policy, and user-facing language. Retain the core user identity contract.
+
+## Verification
+
+Test authorized and forbidden list/view/update operations, cross-workspace
+isolation, missing records, null/cleared fields, filtering, and pagination.
+
+## Avoid
+
+- copying authentication credential tables into the user resource
+- trusting route scope without repository scope
+- adding app-local mechanics already provided by `defineCrudJsonApiFeature()`
+- generator metadata or field questionnaires

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@app/users",
+  "version": "0.0.0",
+  "description": "App-local read-only user administration feature.",
+  "private": true,
+  "type": "module",
+  "exports": {
+    "./server/UsersFeature": "./src/server/UsersFeature.js",
+    "./shared": "./src/shared/index.js"
+  },
+  "dependencies": {
+    "@jskit-ai/crud-core": "0.1.189",
+    "@jskit-ai/resource-crud-core": "0.1.120"
+  },
+  "jskit": {
+    "kind": "runtime",
+    "capabilities": {
+      "provides": [
+        "app.users"
+      ],
+      "requires": [
+        "runtime.http",
+        "runtime.json-rest-api",
+        "runtime.actions",
+        "runtime.database"
+      ]
+    },
+    "runtime": {
+      "server": {
+        "providers": [
+          {
+            "entrypoint": "src/server/UsersFeature.js",
+            "export": "UsersFeature"
+          }
+        ]
+      },
+      "client": {
+        "providers": []
+      }
+    }
+  }
+}

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users/src/server/UsersFeature.js

@@ -0,0 +1,13 @@
+import { defineCrudJsonApiFeature } from "@jskit-ai/crud-core/server/defineCrudJsonApiFeature";
+import { resource } from "../shared/userResource.js";
+
+const UsersFeature = defineCrudJsonApiFeature({
+  resource,
+  id: "app.users",
+  capability: "app.users",
+  surface: "home",
+  ownershipFilter: "public",
+  relativePath: "/users"
+});
+
+export { UsersFeature };

package/skills/jskit/references/patterns/users/user-administration-server/example/packages/users/src/shared/index.js

@@ -0,0 +1 @@
+export { resource } from "./userResource.js";