@bluerobotics/bluevue 0.1.1 → 0.2.1

package/README.md

@@ -1,9 +1,13 @@
 # BlueVue
 
-Blue Robotics Vue components for common UI.
+The Blue Robotics look, for BlueOS extensions.
 
-A small set of Vue 3 controls built with Tailwind, with no UI-framework dependency: they need
-Vue, the Material Design Icons font, and nothing else.
+A Vue 3 kit that gives an extension the page it is laid out on, the controls that go on it, the
+dialogs and notices it talks through, and the calls that reach BlueOS itself. It is built with
+Tailwind and depends on no UI framework: Vue, the Material Design Icons font, and nothing else.
+
+Every component has a page of its own, with a live demo and its API, in the
+[component gallery](https://bluerobotics.github.io/BlueVue/).
 
 ## Install
 
@@ -25,22 +29,31 @@ import '@mdi/font/css/materialdesignicons.css'
 import '@bluerobotics/bluevue/style.css'
 ```
 
+An extension is a `BlueApp` with your panels inside it:
+
 ```vue
 <script setup lang="ts">
-import { BlueInput, BlueSelect } from '@bluerobotics/bluevue'
+import { BlueApp, BlueExpansiblePanel, BlueInput, BlueSwitch, useBlueOs, useBlueSnackbar } from '@bluerobotics/bluevue'
 import { ref } from 'vue'
 
+const { vehicleName } = useBlueOs()
+const { notify } = useBlueSnackbar()
+
 const name = ref('BlueBoat')
-const vehicle = ref('boat')
+const armed = ref(false)
 </script>
 
 <template>
-  <BlueInput v-model="name" label="Name" theme="dark" />
-  <BlueSelect v-model="vehicle" label="Vehicle" theme="dark" :items="[{ name: 'Boat', value: 'boat' }]" />
+  <BlueApp :title="vehicleName ?? 'My extension'">
+    <BlueExpansiblePanel title="Vehicle" theme="dark" :expanded="true">
+      <BlueInput v-model="name" name="name" label="Name" theme="dark" />
+      <BlueSwitch v-model="armed" name="armed" label="Start armed" label-on="Armed" label-off="Safe" theme="dark" />
+    </BlueExpansiblePanel>
+  </BlueApp>
 </template>
 ```
 
-Every control takes a `theme` of `light` or `dark`.
+Every control takes a `theme` of `light` or `dark`. Extensions are dark.
 
 ## Styles
 
@@ -71,7 +84,8 @@ Doing both works and costs only the duplicated utility bytes.
 
 ### Theming
 
-The colours and shadows are CSS custom properties, so an app can restate them:
+The colours and shadows are CSS custom properties, so an app can restate them, either in CSS or
+through `applyBlueTheme({ primary: '#0B5087' })`:
 
 ```css
 :root {
@@ -82,22 +96,76 @@ The colours and shadows are CSS custom properties, so an app can restate them:
 }
 ```
 
-## Components
+## What is in it
+
+**The page**
 
 | Component | What it is |
 | --- | --- |
-| `BlueButtonGroup` | Segmented switch or multi-toggle, with an optional overflow menu |
+| `BlueApp` | The whole page: backdrop, card, and the notices and waits mounted once |
+| `BlueCard` | The sheet a page is laid out on, with a title bar and a footer |
 | `BlueExpansiblePanel` | Titled section that collapses |
+| `BlueSection` | A subject inside a panel |
+
+**Controls**
+
+| Component | What it is |
+| --- | --- |
+| `BlueButton` | Filled, tonal, text or icon, with a loading state |
+| `BlueButtonGroup` | Segmented switch or multi-toggle, with an optional overflow menu |
+| `BlueCheckbox` | A plain yes or no, indeterminate included |
+| `BlueFileDrop` | A place to drop a file on, or press to choose one |
 | `BlueInput` | Text or number field, with a suffix, bounds and validation messages |
-| `BlueLoadingDialog` | Blocking overlay, under a turning propeller, for an operation in progress |
-| `BlueMenu` | Action dropdown, anchored to an activator or to a pointer position |
-| `BluePromptDialog` | Asks for a name, and optionally a note |
+| `BlueWindRose` | A heading, typed or pointed on a compass rose |
+| `BlueRadioGroup` | One choice out of a few, each spelled out |
 | `BlueSelect` | Single or multiple selection from a list |
 | `BlueSlider` | Range with a value pill, editable on double-click |
 | `BlueSwitch` | Two-state switch with its own labels |
+| `BlueTabs` | The strip that switches between the pages of a view |
+| `BlueTextarea` | A `BlueInput` with room for several lines |
 
-`useBluePopover` is also exported, for building further dropdowns on the same top-layer
-placement the menus use.
+**Display**
+
+| Component | What it is |
+| --- | --- |
+| `BlueBanner` / `BlueBannerGroup` | A one-line note that expands, and a stack of them |
+| `BlueChip` | A small standing label: a state, a tag, a count |
+| `BlueIcon` | A Material Design Icon in a square box |
+| `BlueStat` | One read-only fact, in a row of them |
+| `BlueTable` | Rows of records under a header that stays put, ordered by pressing it |
+
+**Overlays**
+
+| Component | What it is |
+| --- | --- |
+| `BlueDialog` | The base every dialog is built on, over the native `<dialog>` |
+| `BlueConfirmDialog` | Asks before something irreversible |
+| `BlueStepsDialog` | Reports work of several steps, with its log |
+| `BlueMenu` | Action dropdown, anchored to an activator or to a pointer position |
+| `BluePromptDialog` | Asks for a name, and optionally a note |
+| `BlueTooltip` | A hint on hover or focus |
+
+**Feedback**
+
+| Component | What it is |
+| --- | --- |
+| `BlueLoadingDialog` | Blocking overlay, under a turning propeller, for an operation in progress |
+| `BlueProgressBar` | How far along something is, or that it is going at all |
+| `BlueSnackbar` | The corner notices are shown in, raised from anywhere |
+| `BlueSpinner` | A turning ring, for a wait with no measure |
+
+**Composables and helpers**
+
+| Export | What it does |
+| --- | --- |
+| `useBlueSnackbar` | Raises a notice, or reports a failed call, from anywhere |
+| `useBlueLoading` | Blocks the page while something is running |
+| `useBlueOs` | What the vehicle calls itself, its version, and its look |
+| `useBlueOsSetting` | A value kept on the vehicle rather than in this browser |
+| `blueOsService` | Any BlueOS service by name, with JSON and errors handled |
+| `useBluePopover` | The top-layer placement the menus and tooltips are built on |
+| `applyBlueTheme` | Restates the tokens at runtime |
+| `downloadJson` / `pickJsonFile` | Saves a profile to disk, and reads one back |
 
 ## Browser support
 
@@ -108,6 +176,17 @@ dialogs use `<dialog>`, so they need Chrome 114, Edge 114, Firefox 125 or Safari
 
 ```bash
 npm install
-npm run dev     # playground on http://localhost:8090
-npm run build   # dist/bluevue.js, dist/index.d.ts and dist/style.css
+npm run dev         # the gallery on http://localhost:8090
+npm run build       # dist/bluevue.js, dist/index.d.ts and dist/style.css
+npm run docs:build  # the gallery as a static site, in docs-dist
+```
+
+## Start an extension
+
+```bash
+npx @bluerobotics/bluevue my-extension
 ```
+
+That copies a Vite + Vue frontend already wired to this package, a FastAPI backend that answers
+`/register_service` with `works_in_relative_paths`, a Dockerfile carrying the labels BlueOS
+installs from, and a GitHub workflow that builds the image.

package/bin/create-blueos-extension.mjs

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+import { cpSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const here = dirname(fileURLToPath(import.meta.url))
+const template = join(here, '..', 'templates', 'extension')
+
+const raw = process.argv[2]
+if (!raw || raw === '--help' || raw === '-h') {
+  console.error('Usage: npx @bluerobotics/bluevue <name>')
+  console.error('Creates a BlueOS extension in ./<name>, wired to this package.')
+  process.exit(raw ? 0 : 1)
+}
+
+const slug = raw
+  .trim()
+  .toLowerCase()
+  .replace(/[^a-z0-9]+/g, '-')
+  .replace(/^-+|-+$/g, '')
+
+if (!slug) {
+  console.error('Give the extension a name made of letters, numbers or hyphens.')
+  process.exit(1)
+}
+
+const title = slug
+  .split('-')
+  .filter(Boolean)
+  .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+  .join(' ')
+
+const dest = resolve(process.cwd(), slug)
+
+try {
+  mkdirSync(dest)
+} catch (error) {
+  if (/** @type {NodeJS.ErrnoException} */ (error).code === 'EEXIST') {
+    console.error(`${dest} already exists.`)
+    process.exit(1)
+  }
+  throw error
+}
+
+cpSync(template, dest, { recursive: true })
+
+const replacements = {
+  __SLUG__: slug,
+  __TITLE__: title,
+}
+
+const walk = (dir) => {
+  for (const entry of readdirSync(dir)) {
+    const path = join(dir, entry)
+    if (statSync(path).isDirectory()) {
+      walk(path)
+      continue
+    }
+    const before = readFileSync(path, 'utf8')
+    const after = Object.entries(replacements).reduce(
+      (text, [token, value]) => text.replaceAll(token, value),
+      before
+    )
+    if (after !== before) writeFileSync(path, after)
+  }
+}
+
+walk(dest)
+
+console.log(`Created ${slug}/
+  cd ${slug}/frontend && npm install && npm run dev
+  The backend is PORT=8000 python backend/main.py, after pip install -r backend/requirements.txt.`)