@synopackageland/sdk 0.9.9 → 0.10.0

package/README.md

@@ -34,6 +34,117 @@ and passes it to `PortalSettings`. `call` reaches the package backend's
 Its `messages` are `portalMessages(locale)`, the panel text from
 `i18n/portal/<locale>.json` (`portalCatalogs`). It has no plain `mountPanel`.
 
+## Full page
+
+A Portal or standalone launch gives the App the whole page; the DSM window
+passes `ctx.fullPage`, `ctx.displayName` and `ctx.appIcon`. `isFullPage(ctx)`
+reads it, and with an older CLI that passes no `fullPage` treats everything
+but a DSM desktop window as a full page. Pass `ctx` to `AppShell` and a full
+page takes the web layout and a device-width viewport, names the App in the
+sidebar and shows the signed-in user, administrator or DSM user, at its foot;
+a DSM window keeps its window layout and title bar. `AppShell` reads only
+`fullPage` (or `host`), `displayName`, `appIcon` and `user` (`ShellContext`),
+so the DSM window's ctx works as it is.
+
+```vue
+<AppShell v-model="page" :ctx="ctx" :locale="ctx.locale" :pages="pages" sidebar-storage-key="HelloGo" />
+```
+
+## Outside DSM
+
+A development page, a preview or a test owns the browser page and has no DSM
+window. `createStandaloneContext({call})` gives it a full-page `Context`
+(`locale: 'en'`, `fullPage: true`, a no-op `reopen`) around the App's own
+`call`; any other field overrides. `createStandaloneHost(platform?)` is its
+`HostAdapter`: `setTitle` titles the document, `openURL` opens an http(s)
+URL in a new tab, `subscribe('window-resize')` follows the browser window,
+and the DSM desktop actions answer `{status: 'unsupported'}`. Platform fields
+override the snapshot, so a test can stand in for a DSM window
+(`createStandaloneHost({host: 'dsm', dsmStandalone: false})`).
+
+```ts
+const ctx = createStandaloneContext({locale: 'zh-TW', call: (method, params) => post('/api', {method, params})})
+```
+
+## App pages
+
+`AppShell` lays out the App's own pages too. Each `AppShellPage` has an `id`,
+a `title` the App has already translated, and optionally an `icon`, a `group`
+label (pages with the same label sit together), a `badge`, a `component` to
+render while it is the current page, `hidden` (reachable through `v-model`
+but not in the sidebar), its own `description`, and `header: false` for a
+page that draws its own header. `fill: true` gives the page's body the height under
+its header and notices; the page does not scroll, so the content scrolls
+itself (a treemap, a table paged by height, a log viewer). The shell then
+holds to `100dvh`, so a phone's address bar does not leave a gap. The built-in `'status'` and `'background'`
+may sit in the same list.
+
+```vue
+<AppShell v-model="page" :ctx="ctx" :locale="ctx.locale" :pages="[
+  {id: 'downloads', title: t('downloads'), icon: Download, badge: running || undefined, component: DownloadsPage},
+  {id: 'settings', title: t('settings'), icon: Settings, group: t('admin')},
+  'background',
+]" page-width="fill">
+  <template #actions="{page}"><Button v-if="page === 'downloads'" @click="add">{{ t('add') }}</Button></template>
+  <template #notices><JobStrip v-for="job in jobs" :key="job.id" :job="job" /></template>
+  <template #default="{page}"><SettingsPage v-show="page === 'settings'" /></template>
+</AppShell>
+```
+
+Moving to another page starts it at the top; `keep-scroll` keeps the
+position. The `toolbar` slot sits above the page (in `AppLayout`'s toolbar)
+and `notices` in the page, under its header and inside the same padding, and
+scrolls with it. `activePage(current, pages)` keeps a selection that still exists and
+otherwise picks the first page the sidebar shows. A router drives the shell
+through `v-model`:
+`:model-value="route.name" @update:model-value="name => router.push({name})"`.
+
+## App root
+
+`app-root` wraps the shell in an app-local `AppRoot`
+(`modal-scope="app"`, `height: 100%`) and a `ConfigProvider` with the
+shell's `locale`, so the UI components' own text follows it. In a DSM desktop window (a `ctx` that
+is not a full page) its dialogs may leave the window (`dialog-bounds=
+"viewport"`), and a press on a floating dialog calls
+`ctx.host.activateWindow()`, which brings the window to the front; a full
+page and a shell without `ctx` keep dialogs in the App. Use it in place of
+the App's own `AppRoot`: app-local roots do not nest.
+
+```vue
+<AppShell app-root v-model="page" :ctx="ctx" :locale="ctx.locale" :pages="pages" />
+```
+
+## Denied access
+
+`denied` replaces the App's pages with one page that says the account may
+not use the App: a `No access` header and a message pointing to DSM
+Application Privileges, in every UI locale (`shellCopy`'s `deniedTitle` and
+`deniedMessage`). `denied` is `true` or an `AppShellDenied` (`title`,
+`message`, `header: false`); the `denied` slot replaces the message, for
+example with a sign-in form. The sidebar, the notices and the default slot
+are not rendered meanwhile.
+
+```vue
+<AppShell v-model="page" :ctx="ctx" :locale="ctx.locale" :pages="pages" :denied="!authorized && {title: t('privilegeTitle')}" />
+<AppShell v-model="page" :ctx="ctx" :locale="ctx.locale" :pages="pages" :denied="signInNeeded && {header: false}">
+  <template #denied><LoginPage :session="login" :locale="ctx.locale" /></template>
+</AppShell>
+```
+
+## Calling the backend
+
+`ctx.call(method, params, {signal})` posts to the package backend. An abort of
+`signal` rejects it with `{code: 'request_canceled'}`, for a page the user
+leaves; past `clientTimeout(ctx.requestTimeout)` it rejects with `{code:
+'request_timeout'}`.
+Without `ctx.requestTimeout` the deadline is `DEFAULT_REQUEST_TIMEOUT`, 60
+seconds like the backend's, and the client waits 62.
+
+```ts
+const controller = new AbortController()
+const items = await ctx.call<Item[]>('items.list', {}, {signal: controller.signal})
+```
+
 ## Localized copy
 
 `format(message, values, locale)` fills `{key}` placeholders from `values`; a
@@ -52,6 +163,12 @@ format(copy[locale].files, {count: 3, folder: 'photo'}, locale) // {"one": "{cou
 `mergeCatalogs` layers the App's catalogs over the SDK's, key by key; for each
 key the order is the App's locale, the SDK's locale, then `en`.
 
+`bridgeErrorCopy(error, locale)` is the text of a code that the bridge runtime
+adds for Python, Node and Rust Apps: `app_unavailable`, and the services'
+`limit_exceeded`, `read_failed` and `identity_unavailable`. For any other code
+it returns `undefined`, so the App falls back to its own text. Its catalogs,
+`i18n/bridge/<locale>.json`, are generated from `spec/bridge/v1/errors.json`.
+
 The Vue entry needs the peer dependencies `vue`, `@synopackageland/ui` and
 `@lucide/vue`. The headless entry needs none.
 
@@ -64,6 +181,10 @@ npm run typecheck
 npm run build
 ```
 
+After a change to `../spec/bridge/v1/errors.json`, run `node
+scripts/gen-bridge-i18n.mjs`; `npm test` fails while `i18n/bridge/` differs
+from it.
+
 `npm run build` also copies `../spec` into `spec/`. Run `npm ci` before
 `npm pack`: `prepack` builds and needs `node_modules`. `npm install
 --install-links` from a checkout does not run `prepack`, so build first.

package/dist/i18n/bridge/de.json

@@ -0,0 +1,6 @@
+{
+  "app_unavailable": "Die App ist derzeit nicht verfügbar. Versuchen Sie es später erneut.",
+  "limit_exceeded": "Die Datei ist größer als zulässig.",
+  "read_failed": "Die Datei kann nicht gelesen werden. Bitte versuchen Sie es später erneut.",
+  "identity_unavailable": "Dieses Benutzerkonto kann nicht ermittelt werden. Bitte versuchen Sie es später erneut."
+}

package/dist/i18n/bridge/en.json

@@ -0,0 +1,6 @@
+{
+  "app_unavailable": "The App is not available right now. Try again later.",
+  "limit_exceeded": "The file is larger than allowed.",
+  "read_failed": "Unable to read the file. Please try again later.",
+  "identity_unavailable": "Unable to identify this user account. Please try again later."
+}

package/dist/i18n/bridge/es.json

@@ -0,0 +1,6 @@
+{
+  "app_unavailable": "La App no está disponible en este momento. Vuelva a intentarlo más tarde.",
+  "limit_exceeded": "El archivo supera el tamaño permitido.",
+  "read_failed": "No se puede leer el archivo. Vuelva a intentarlo más tarde.",
+  "identity_unavailable": "No se puede identificar esta cuenta de usuario. Vuelva a intentarlo más tarde."
+}

package/dist/i18n/bridge/fr.json

@@ -0,0 +1,6 @@
+{
+  "app_unavailable": "L’App n’est pas disponible pour le moment. Réessayez plus tard.",
+  "limit_exceeded": "Le fichier dépasse la taille autorisée.",
+  "read_failed": "Impossible de lire le fichier. Veuillez réessayer ultérieurement.",
+  "identity_unavailable": "Impossible d'identifier ce compte utilisateur. Veuillez réessayer ultérieurement."
+}

package/dist/i18n/bridge/it.json

@@ -0,0 +1,6 @@
+{
+  "app_unavailable": "L’App non è al momento disponibile. Riprovare più tardi.",
+  "limit_exceeded": "Il file supera le dimensioni consentite.",
+  "read_failed": "Impossibile leggere il file. Riprovare più tardi.",
+  "identity_unavailable": "Impossibile identificare questo account utente. Riprovare più tardi."
+}

package/dist/i18n/bridge/ja.json

@@ -0,0 +1,6 @@
+{
+  "app_unavailable": "App は現在使用できません。しばらくしてから再試行してください。",
+  "limit_exceeded": "ファイルが許可されたサイズを超えています。",
+  "read_failed": "ファイルを読み取れません。後でもう一度お試しください。",
+  "identity_unavailable": "このユーザー アカウントを識別できません。後でもう一度お試しください。"
+}

package/dist/i18n/bridge/ko.json

@@ -0,0 +1,6 @@
+{
+  "app_unavailable": "현재 App을 사용할 수 없습니다. 나중에 다시 시도하십시오.",
+  "limit_exceeded": "파일이 허용된 크기를 초과합니다.",
+  "read_failed": "파일을 읽을 수 없습니다. 나중에 다시 시도하십시오.",
+  "identity_unavailable": "이 사용자 계정을 확인할 수 없습니다. 나중에 다시 시도하십시오."
+}

package/dist/i18n/bridge/zh-CN.json

@@ -0,0 +1,6 @@
+{
+  "app_unavailable": "App 当前不可用，请稍后重试。",
+  "limit_exceeded": "文件超过允许的大小。",
+  "read_failed": "无法读取文件。请稍后再试。",
+  "identity_unavailable": "无法识别此用户帐号。请稍后再试。"
+}

package/dist/i18n/bridge/zh-TW.json

@@ -0,0 +1,6 @@
+{
+  "app_unavailable": "App 目前無法使用，請稍後再試。",
+  "limit_exceeded": "檔案超過允許的大小。",
+  "read_failed": "無法讀取檔案。請稍後再試。",
+  "identity_unavailable": "無法識別此使用者帳號。請稍後再試。"
+}

package/dist/i18n/shell/de.json

@@ -1,4 +1,8 @@
 {
   "status": "Status",
-  "background": "Hintergrundaufträge"
+  "background": "Hintergrundaufträge",
+  "administrator": "Administrator",
+  "dsmUser": "DSM-Benutzer",
+  "deniedTitle": "Kein Zugriff",
+  "deniedMessage": "Ihr DSM-Konto darf diese App nicht verwenden. Bitten Sie einen Administrator, sie in den DSM-Anwendungsberechtigungen freizugeben."
 }

package/dist/i18n/shell/en.json

@@ -1,4 +1,8 @@
 {
   "status": "Status",
-  "background": "Background jobs"
+  "background": "Background jobs",
+  "administrator": "Administrator",
+  "dsmUser": "DSM user",
+  "deniedTitle": "No access",
+  "deniedMessage": "Your DSM account is not allowed to use this app. Ask an administrator to allow it in DSM Application Privileges."
 }

package/dist/i18n/shell/es.json

@@ -1,4 +1,8 @@
 {
   "status": "Estado",
-  "background": "Tareas en segundo plano"
+  "background": "Tareas en segundo plano",
+  "administrator": "Administrador",
+  "dsmUser": "Usuario DSM",
+  "deniedTitle": "Sin acceso",
+  "deniedMessage": "Su cuenta de DSM no tiene permiso para usar esta aplicación. Pida a un administrador que la permita en los privilegios de aplicaciones de DSM."
 }

package/dist/i18n/shell/fr.json

@@ -1,4 +1,8 @@
 {
   "status": "Statut",
-  "background": "Tâches en arrière-plan"
+  "background": "Tâches en arrière-plan",
+  "administrator": "Administrateur",
+  "dsmUser": "Utilisateur DSM",
+  "deniedTitle": "Accès refusé",
+  "deniedMessage": "Votre compte DSM n’est pas autorisé à utiliser cette application. Demandez à un administrateur de l’autoriser dans les privilèges d’application de DSM."
 }

package/dist/i18n/shell/it.json

@@ -1,4 +1,8 @@
 {
   "status": "Stato",
-  "background": "Attività in background"
+  "background": "Attività in background",
+  "administrator": "Amministratore",
+  "dsmUser": "Utente DSM",
+  "deniedTitle": "Accesso negato",
+  "deniedMessage": "L’account DSM non è autorizzato a usare questa app. Chiedere a un amministratore di consentirlo nei privilegi delle applicazioni DSM."
 }

package/dist/i18n/shell/ja.json

@@ -1,4 +1,8 @@
 {
   "status": "状態",
-  "background": "バックグラウンドジョブ"
+  "background": "バックグラウンドジョブ",
+  "administrator": "管理者",
+  "dsmUser": "DSM ユーザー",
+  "deniedTitle": "アクセスできません",
+  "deniedMessage": "この DSM アカウントにはこのアプリを使用する権限がありません。DSM のアプリケーション権限で許可するよう管理者に依頼してください。"
 }

package/dist/i18n/shell/ko.json

@@ -1,4 +1,8 @@
 {
   "status": "상태",
-  "background": "백그라운드 작업"
+  "background": "백그라운드 작업",
+  "administrator": "관리자",
+  "dsmUser": "DSM 사용자",
+  "deniedTitle": "액세스할 수 없음",
+  "deniedMessage": "이 DSM 계정에는 이 앱을 사용할 권한이 없습니다. 관리자에게 DSM 응용 프로그램 권한에서 허용하도록 요청하십시오."
 }

package/dist/i18n/shell/zh-CN.json

@@ -1,4 +1,8 @@
 {
   "status": "状态",
-  "background": "后台工作"
+  "background": "后台工作",
+  "administrator": "管理员",
+  "dsmUser": "DSM 用户",
+  "deniedTitle": "无法访问",
+  "deniedMessage": "你的 DSM 帐号无权使用此应用程序。请管理员在 DSM 的应用程序权限中开放给你。"
 }

package/dist/i18n/shell/zh-TW.json

@@ -1,4 +1,8 @@
 {
   "status": "狀態",
-  "background": "背景工作"
+  "background": "背景工作",
+  "administrator": "管理員",
+  "dsmUser": "DSM 使用者",
+  "deniedTitle": "無法存取",
+  "deniedMessage": "你的 DSM 帳號無權使用此應用程式。請管理員在 DSM 的應用程式權限中開放給你。"
 }