@bluerobotics/bluevue 0.1.0 → 0.2.0

package/src/services/blueos.ts

@@ -0,0 +1,95 @@
+/** What a BlueOS service answered when it did not answer with the thing that was asked for. */
+export class BlueOsError extends Error {
+  constructor(
+    message: string,
+    readonly url: string,
+    /** The HTTP status, or 0 when the service could not be reached at all. */
+    readonly status: number
+  ) {
+    super(message)
+    this.name = 'BlueOsError'
+  }
+}
+
+export interface BlueOsServiceOptions {
+  /** The API version the service is versioned under. Pass null for the few that are not. */
+  version?: string | null
+  /** How long a call may take before it is given up on, in milliseconds. */
+  timeout?: number
+}
+
+export interface BlueOsService {
+  /** The absolute path a call would be made to, for a request this wrapper does not cover. */
+  url: (path: string) => string
+  get: <T>(path: string, init?: RequestInit) => Promise<T>
+  post: <T>(path: string, body?: unknown, init?: RequestInit) => Promise<T>
+  delete: <T>(path: string, init?: RequestInit) => Promise<T>
+}
+
+// An extension is served from the same origin as BlueOS itself, so the services sit at the root of
+// it and a relative path reaches them. A page being developed off the vehicle is the exception,
+// and it says where the vehicle is.
+let host = ''
+
+/**
+ * Points the services at a BlueOS that is not the origin serving this page, which is what a page
+ * running on a development server needs.
+ * @param {string} url The vehicle's address, such as 'http://blueos.local'. Empty means the origin.
+ */
+export const setBlueOsHost = (url: string): void => {
+  host = url.replace(/\/$/, '')
+}
+
+/** Whether this page is being served by BlueOS as an extension, rather than run on its own. */
+export const isBlueOsExtension = (): boolean =>
+  typeof window !== 'undefined' && window.location.pathname.startsWith('/extensionv2/')
+
+/**
+ * A wrapper around one of BlueOS's services, reachable by name.
+ * @param {string} name The service as nginx exposes it, such as 'beacon', 'bag' or 'kraken'.
+ * @param {BlueOsServiceOptions} options The API version to address and how long to wait.
+ * @returns {BlueOsService} Its verbs, each parsing JSON and raising BlueOsError on anything else.
+ */
+export const blueOsService = (name: string, options: BlueOsServiceOptions = {}): BlueOsService => {
+  const version = options.version === undefined ? 'v1.0' : options.version
+  const timeout = options.timeout ?? 5000
+
+  const url = (path: string): string => {
+    const segments = [name, version, path.replace(/^\//, '')].filter((part): part is string => Boolean(part))
+    return `${host}/${segments.join('/')}`
+  }
+
+  const request = async <T>(path: string, init: RequestInit): Promise<T> => {
+    const target = url(path)
+
+    let response: Response
+    try {
+      response = await fetch(target, { signal: AbortSignal.timeout(timeout), ...init })
+    } catch (error) {
+      // A refused connection, a DNS failure and a timeout all mean the same thing to a page: the
+      // vehicle is not answering, which is worth saying differently from a service that refused.
+      throw new BlueOsError(`Could not reach ${name}: ${(error as Error).message}`, target, 0)
+    }
+
+    if (!response.ok) {
+      throw new BlueOsError(await response.text() || response.statusText, target, response.status)
+    }
+
+    // A service that answers with nothing is answering successfully, and undefined is what that is.
+    const text = await response.text()
+    return (text === '' ? undefined : JSON.parse(text)) as T
+  }
+
+  return {
+    url,
+    get: <T>(path: string, init?: RequestInit) => request<T>(path, { method: 'GET', ...init }),
+    post: <T>(path: string, body?: unknown, init?: RequestInit) =>
+      request<T>(path, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: body === undefined ? undefined : JSON.stringify(body),
+        ...init,
+      }),
+    delete: <T>(path: string, init?: RequestInit) => request<T>(path, { method: 'DELETE', ...init }),
+  }
+}

package/src/styles/bluevue.css

@@ -17,6 +17,9 @@
      rather than somewhere that is pressed. The light line along the bottom edge is what sells
      the depth, by reading as the lit far wall of the recess. */
   --bluevue-inset-1: inset 0 1px 2px #00000056, inset 0 0.5px 0.5px #0000003a, inset 0 -0.5px 0 #ffffff0b;
+  /* The elevation the buttons rest at, with each of its three shadows at half the alpha: a note is
+     raised off the surface less than something meant to be pressed. */
+  --bluevue-elevation-1-soft: 0 2px 1px -1px #0000001a, 0 1px 1px 0 #00000012, 0 1px 3px 0 #0000000f;
 }
 
 .bluevue-elevation-1 {
@@ -31,6 +34,10 @@
   box-shadow: var(--bluevue-inset-1);
 }
 
+.bluevue-elevation-1-soft {
+  box-shadow: var(--bluevue-elevation-1-soft);
+}
+
 /* The surface the dialogs are built on: a frosted near-black card with a hairline edge. */
 .bluevue-panel {
   background-color: var(--bluevue-panel-bg);
@@ -80,6 +87,135 @@
   overflow: visible;
 }
 
+/* An icon is a box the size of its em, not of however wide its glyph advances, so a row of them
+   lines up. Written against .mdi as well, since the icon font's own rules say otherwise and a
+   consumer is free to load the two stylesheets in either order. */
+.mdi.bluevue-icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+  line-height: 1;
+}
+
+.bluevue-icon--spin {
+  animation: bluevue-spin 1.2s linear infinite;
+}
+
+/* The ring is a circle with one lit quarter, turning. */
+.bluevue-spinner {
+  display: inline-block;
+  box-sizing: border-box;
+  flex-shrink: 0;
+  border-radius: 9999px;
+  border-style: solid;
+  border-color: #ffffff2e;
+  border-top-color: var(--bluevue-accent);
+  animation: bluevue-spin 0.8s linear infinite;
+}
+
+@keyframes bluevue-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+/* Progress with no measure to it: a short bar crossing the track, rather than a fill that would
+   have to claim a position it does not know. */
+.bluevue-progress__sweep {
+  width: 40%;
+  animation: bluevue-progress-sweep 1.4s ease-in-out infinite;
+}
+
+@keyframes bluevue-progress-sweep {
+  from {
+    transform: translateX(-100%);
+  }
+  to {
+    transform: translateX(250%);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .bluevue-icon--spin,
+  .bluevue-spinner,
+  .bluevue-progress__sweep {
+    animation-duration: 3s;
+  }
+}
+
+/* A banner's metrics live here, not in utility classes: Tailwind's utilities sit in a cascade layer
+   and a host application's reset does not, so a rule as broad as Vuetify's `* { padding: 0 }` beats
+   them whatever their selectors say, and the shut banner is left without the padding that makes it
+   a square. */
+.bluevue-banner {
+  box-sizing: border-box;
+  height: 26px;
+  padding: 4px;
+  font-size: 12px;
+  line-height: 16px;
+  /* Squeezed by the row it shares in a group, it loses the tail of its message rather than painting
+     it outside its own rounded box. */
+  overflow: hidden;
+}
+
+/* A box the size of the em, not of however wide the glyph happens to advance, so the shut banner is
+   26 x 26 whichever icon it carries. */
+.bluevue-banner__icon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 16px;
+  height: 16px;
+  font-size: 16px;
+  line-height: 16px;
+}
+
+/* The message's gutter rides inside the window that opens, so the shut square keeps the even four
+   pixels around its icon. */
+.bluevue-banner__text {
+  padding: 0 8px;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+/* Width is the whole of the animation: the row is as tall as its icon whether it is shut or open,
+   so nothing above or below the message moves and the banner only ever grows to the right. */
+.bluevue-banner__reveal {
+  transition: width 260ms ease-in-out;
+}
+
+/* Measuring lays the message out by its content and puts it back; no frame is painted in between,
+   but the geometry it reads would otherwise be somewhere for an animation to start from. */
+.bluevue-banner--measuring .bluevue-banner__reveal {
+  transition: none;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .bluevue-banner__reveal {
+    transition: none;
+  }
+}
+
+/* A notice arrives from the edge it stacks against and leaves the same way, and the ones left
+   behind slide up into the gap rather than jumping. */
+.bluevue-notice-enter-active,
+.bluevue-notice-leave-active,
+.bluevue-notice-move {
+  transition: opacity 180ms ease, transform 180ms ease;
+}
+
+.bluevue-notice-enter-from,
+.bluevue-notice-leave-to {
+  opacity: 0;
+  transform: translateY(8px);
+}
+
+.bluevue-notice-leave-active {
+  position: absolute;
+}
+
 /* BlueExpansiblePanel's open and close. */
 .bluevue-expand-enter-active,
 .bluevue-expand-leave-active {

package/src/types/banner.ts

@@ -0,0 +1,17 @@
+export type BannerSeverity = 'error' | 'warning' | 'info' | 'success'
+
+/** A banner's message and look, which is all a group needs to lay one out. */
+export interface BannerContent {
+  /** The message, which the banner is only as wide as while it is open. */
+  text: string
+  /** Which of the standard looks to take (default 'info'). */
+  severity?: BannerSeverity
+  /** An mdi class, in place of the severity's icon. */
+  icon?: string
+  /** Icon and text colour, in place of the severity's. */
+  color?: string
+  /** Fill, in place of the severity's. */
+  background?: string
+  /** Hairline, in place of the severity's. */
+  border?: string
+}

package/src/utils/files.ts

@@ -0,0 +1,44 @@
+/**
+ * Saves an object as a JSON file the browser downloads. What an extension's "export configuration"
+ * button does.
+ * @param {unknown} data Anything JSON can hold.
+ * @param {string} filename Suggested name. '.json' is appended when it is missing.
+ */
+export function downloadJson(data: unknown, filename: string): void {
+  const name = filename.endsWith('.json') ? filename : `${filename}.json`
+  const url = URL.createObjectURL(new Blob([JSON.stringify(data, null, 2)], { type: 'application/json' }))
+  const link = document.createElement('a')
+  link.href = url
+  link.download = name
+  link.click()
+  // The object URL holds the blob alive until it is released, and the click has already been
+  // handed the data by the time this runs.
+  URL.revokeObjectURL(url)
+}
+
+/**
+ * Asks for a JSON file and parses it. Resolves to null when the picker is closed without a choice.
+ * @param {string} accept File types to offer (default '.json,application/json').
+ * @returns {Promise<T | null>} The parsed contents, or null. A malformed file rejects.
+ */
+export function pickJsonFile<T = unknown>(accept = '.json,application/json'): Promise<T | null> {
+  return new Promise((resolve, reject) => {
+    const input = document.createElement('input')
+    input.type = 'file'
+    input.accept = accept
+    // A picker closed with Escape fires nothing at all in some browsers, so the promise is left to
+    // settle on the next choice rather than being resolved from a cancel event that may not come.
+    input.addEventListener('change', () => {
+      const file = input.files?.[0]
+      if (!file) {
+        resolve(null)
+        return
+      }
+      file
+        .text()
+        .then((text) => resolve(JSON.parse(text) as T))
+        .catch(reject)
+    })
+    input.click()
+  })
+}

package/src/utils/theme.ts

@@ -0,0 +1,37 @@
+/** Every token the components read, in the names they are written with. */
+export interface BlueTheme {
+  /** Fills a committing button, a selected segment, a slider's pill. */
+  primary?: string
+  /** The lighter blue used where the primary would disappear into a dark inset, such as a focus ring. */
+  accent?: string
+  /** Anything that went wrong, or is about to. */
+  error?: string
+  /** The card an extension's page is laid out on. */
+  surface?: string
+  /** The frosted panel dialogs and menus are drawn on. */
+  panelBg?: string
+  /** The line dividing one part of a panel from the next. */
+  hairline?: string
+}
+
+const VARIABLE: Record<keyof BlueTheme, string> = {
+  primary: '--bluevue-primary',
+  accent: '--bluevue-accent',
+  error: '--bluevue-error',
+  surface: '--bluevue-surface',
+  panelBg: '--bluevue-panel-bg',
+  hairline: '--bluevue-hairline',
+}
+
+/**
+ * Repaints the kit in an extension's own colours, or in the colours BlueOS reports for the vehicle.
+ * Only the tokens given are touched, so the rest keep the values the stylesheet ships with.
+ * @param {BlueTheme} theme The tokens to change.
+ * @param {HTMLElement} target Where to set them (default the document root, so they reach everything).
+ */
+export function applyBlueTheme(theme: BlueTheme, target: HTMLElement = document.documentElement): void {
+  for (const [key, variable] of Object.entries(VARIABLE) as [keyof BlueTheme, string][]) {
+    const value = theme[key]
+    if (value) target.style.setProperty(variable, value)
+  }
+}

package/templates/extension/.github/workflows/deploy.yml

@@ -0,0 +1,23 @@
+name: Deploy BlueOS Extension Image
+
+on:
+  push:
+  workflow_dispatch:
+
+jobs:
+  deploy-docker-image:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy BlueOS Extension
+        uses: BlueOS-community/Deploy-BlueOS-Extension@v1
+        with:
+          docker-username: ${{ secrets.DOCKER_USERNAME }}
+          docker-password: ${{ secrets.DOCKER_PASSWORD }}
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+          image-name: '__SLUG__'
+          image-prefix: 'blueos-'
+          author: ${{ vars.MY_NAME }}
+          author-email: ${{ vars.MY_EMAIL }}
+          maintainer: ${{ vars.ORG_NAME }}
+          maintainer-email: ${{ vars.ORG_EMAIL }}
+          build-platforms: linux/arm64,linux/amd64,linux/arm/v7

package/templates/extension/Dockerfile

@@ -0,0 +1,56 @@
+# syntax=docker/dockerfile:1
+
+FROM --platform=$BUILDPLATFORM node:20-bookworm-slim AS frontend-builder
+WORKDIR /frontend
+COPY frontend/package.json ./
+RUN npm install
+COPY frontend/ ./
+RUN npm run build
+
+FROM python:3.11-slim AS runtime
+WORKDIR /app
+
+COPY backend/requirements.txt ./requirements.txt
+RUN python -m pip install --no-cache-dir -r requirements.txt
+
+COPY backend/ ./
+COPY --from=frontend-builder /frontend/dist ./static
+
+EXPOSE 80
+
+LABEL version="0.1.0"
+
+LABEL permissions='{\
+  "ExposedPorts": {\
+    "80/tcp": {}\
+  },\
+  "HostConfig": {\
+    "ExtraHosts": ["host.docker.internal:host-gateway"],\
+    "PortBindings": {\
+      "80/tcp": [\
+        {\
+          "HostPort": ""\
+        }\
+      ]\
+    }\
+  }\
+}'
+
+LABEL authors='[\
+  {\
+    "name": "Blue Robotics",\
+    "email": "support@bluerobotics.com"\
+  }\
+]'
+
+LABEL company='{\
+  "about": "A BlueOS extension.",\
+  "name": "Blue Robotics",\
+  "email": "support@bluerobotics.com"\
+}'
+
+LABEL type="tool"
+LABEL tags='["extension"]'
+LABEL requirements="core >= 1.1"
+
+CMD ["python", "main.py"]

package/templates/extension/README.md

@@ -0,0 +1,35 @@
+# __TITLE__
+
+A BlueOS extension, laid out with [@bluerobotics/bluevue](https://github.com/bluerobotics/BlueVue).
+
+## Develop
+
+The frontend is a Vite app. From `frontend/`:
+
+```bash
+npm install
+npm run dev
+```
+
+It answers on http://localhost:8080 and proxies `/register_service` and `/v1.0` to the backend.
+
+The backend is FastAPI. From `backend/`:
+
+```bash
+python -m pip install -r requirements.txt
+PORT=8000 python main.py
+```
+
+It answers on http://localhost:8000. Point the kit at a vehicle while developing off one:
+
+```ts
+import { setBlueOsHost } from '@bluerobotics/bluevue'
+
+setBlueOsHost('http://blueos.local')
+```
+
+## Ship
+
+The Dockerfile builds the frontend, copies it next to the backend, and carries the labels BlueOS
+reads to install the image. The workflow in `.github/workflows/deploy.yml` builds it for amd64,
+arm64 and armv7 on every push, using [Deploy-BlueOS-Extension](https://github.com/BlueOS-community/Deploy-BlueOS-Extension).

package/templates/extension/backend/main.py

@@ -0,0 +1,45 @@
+#! /usr/bin/env python3
+import os
+from pathlib import Path
+from typing import Any, Dict
+
+from fastapi import FastAPI
+from fastapi.staticfiles import StaticFiles
+from uvicorn import Config, Server
+
+PORT = int(os.environ.get("PORT", "80"))
+STATIC_DIR = Path(__file__).resolve().parent / "static"
+
+app = FastAPI(title="__TITLE__")
+
+
+@app.get("/register_service", include_in_schema=False)
+def register_service() -> Dict[str, Any]:
+    """Metadata consumed by BlueOS to add this extension to the sidebar."""
+    return {
+        "name": "__TITLE__",
+        "description": "A BlueOS extension.",
+        "icon": "mdi-puzzle-outline",
+        "company": "Blue Robotics",
+        "version": "0.1.0",
+        "new_page": False,
+        "api": "/docs",
+        "works_in_relative_paths": True,
+    }
+
+
+@app.get("/v1.0/health")
+def health() -> Dict[str, str]:
+    return {"status": "ok"}
+
+
+if STATIC_DIR.is_dir():
+    app.mount("/", StaticFiles(directory=str(STATIC_DIR), html=True), name="static")
+
+
+def main() -> None:
+    Server(Config(app=app, host="0.0.0.0", port=PORT, log_config=None)).run()
+
+
+if __name__ == "__main__":
+    main()

package/templates/extension/backend/requirements.txt

@@ -0,0 +1,2 @@
+fastapi==0.105.0
+uvicorn==0.18.0

package/templates/extension/frontend/.eslintrc.cjs

@@ -0,0 +1,20 @@
+module.exports = {
+  root: true,
+  env: {
+    browser: true,
+    es2022: true,
+  },
+  extends: [
+    'plugin:vue/vue3-recommended',
+    'plugin:@typescript-eslint/recommended',
+  ],
+  parser: 'vue-eslint-parser',
+  parserOptions: {
+    parser: '@typescript-eslint/parser',
+    ecmaVersion: 'latest',
+    sourceType: 'module',
+  },
+  rules: {
+    'vue/multi-word-component-names': 'off',
+  },
+}

package/templates/extension/frontend/env.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="vite/client" />
+
+declare module '*.vue' {
+  import type { DefineComponent } from 'vue'
+  const component: DefineComponent<object, object, unknown>
+  export default component
+}

package/templates/extension/frontend/index.html

@@ -0,0 +1,12 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>__TITLE__</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

package/templates/extension/frontend/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "__SLUG__-frontend",
+  "version": "0.1.0",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "vite",
+    "build": "vue-tsc --noEmit && vite build",
+    "preview": "vite preview",
+    "typecheck": "vue-tsc --noEmit",
+    "lint": "eslint . --ext .vue,.ts"
+  },
+  "dependencies": {
+    "@bluerobotics/bluevue": "^0.2.0",
+    "@mdi/font": "7.4.47",
+    "vue": "3.4.38"
+  },
+  "devDependencies": {
+    "@tailwindcss/vite": "4.1.11",
+    "@typescript-eslint/eslint-plugin": "7.18.0",
+    "@typescript-eslint/parser": "7.18.0",
+    "@vitejs/plugin-vue": "5.1.3",
+    "eslint": "8.57.0",
+    "eslint-plugin-vue": "9.27.0",
+    "tailwindcss": "4.1.11",
+    "typescript": "5.5.4",
+    "vite": "5.4.2",
+    "vue-tsc": "2.0.29"
+  }
+}

package/templates/extension/frontend/src/App.vue

@@ -0,0 +1,51 @@
+<script setup lang="ts">
+import { BlueApp, BlueButton, BlueExpansiblePanel, BlueStat, useBlueOs, useBlueSnackbar } from '@bluerobotics/bluevue'
+
+const { vehicleName, version } = useBlueOs()
+const { notify, notifyError } = useBlueSnackbar()
+
+async function ping(): Promise<void> {
+  try {
+    const response = await fetch('./v1.0/health')
+    if (!response.ok) throw new Error(response.statusText)
+    notify('The extension backend answered.', { severity: 'success' })
+  } catch (error) {
+    notifyError(error, 'Could not reach the extension backend')
+  }
+}
+</script>
+
+<template>
+  <BlueApp title="__TITLE__">
+    <template #actions>
+      <BlueButton
+        variant="icon"
+        icon="mdi-refresh"
+        tooltip="Ask the backend"
+        @click="ping"
+      />
+    </template>
+
+    <div class="mb-4 flex flex-wrap gap-2">
+      <BlueStat
+        label="Vehicle"
+        :value="vehicleName"
+      />
+      <BlueStat
+        label="BlueOS"
+        :value="version"
+      />
+    </div>
+
+    <BlueExpansiblePanel
+      title="Getting started"
+      theme="dark"
+      :expanded="true"
+    >
+      <p class="text-sm leading-relaxed text-[#ffffffcc]">
+        This page is a BlueApp. The notices and the blocking wait are already mounted, so
+        useBlueSnackbar and useBlueLoading work from anywhere. Replace this panel with yours.
+      </p>
+    </BlueExpansiblePanel>
+  </BlueApp>
+</template>

package/templates/extension/frontend/src/main.ts

@@ -0,0 +1,8 @@
+import '@mdi/font/css/materialdesignicons.css'
+import '@/styles/global.css'
+
+import { createApp } from 'vue'
+
+import App from './App.vue'
+
+createApp(App).mount('#app')

package/templates/extension/frontend/src/styles/global.css

@@ -0,0 +1,11 @@
+@import "tailwindcss";
+@import "@bluerobotics/bluevue/bluevue.css";
+
+@source "../../node_modules/@bluerobotics/bluevue/dist";
+
+html,
+body,
+#app {
+  margin: 0;
+  min-height: 100%;
+}