@sensolus/create-snt-agent-app 0.2.0 → 0.3.0

package/README.md

@@ -0,0 +1,153 @@
+# @sensolus/create-snt-agent-app
+
+Scaffold a new Sensolus agent app: a React (Vite) frontend wired to
+[`@sensolus/snt-agent-kit`](https://www.npmjs.com/package/@sensolus/snt-agent-kit)
+plus a Flask backend that proxies the Sensolus public API, with PostgreSQL,
+migrations, Docker, and Jenkins CI included.
+
+## Quick start — create an agent app
+
+```bash
+npm create @sensolus/snt-agent-app my-app
+cd my-app
+cp .env.example .env        # fill in MAPBOX_KEY + LOCATIONIQ_KEY (required for SntMap)
+npm install
+pip install -r backend/requirements.txt
+npm run dev                 # frontend on :3000
+python backend/app.py       # backend on :5000 (separate terminal)
+```
+
+Open http://localhost:3000. The Vite dev server proxies `/api/*` to Flask;
+Flask serves runtime config (map keys) at `/api/config` and proxies the
+Sensolus API with your session cookie or an API key entered in the app.
+
+The generated README covers the rest: PostgreSQL setup, Docker build,
+deployment, and environment variables.
+
+### Rules of the road
+
+Widgets, theme, and the i18n framework come from `@sensolus/snt-agent-kit` —
+**import them, don't copy them**. ESLint in the generated app enforces no deep
+imports and no `Snt*` re-declarations. App-specific translation keys live in
+your app (`src/i18n/messages.js`) and are merged via
+`<LocaleProvider messages={...}>`.
+
+## The widget kit
+
+The generated app comes pre-wired, but everything below is plain
+`@sensolus/snt-agent-kit` API — useful when extending the app.
+
+### Default wiring (generated-app convention)
+
+The app proxies the Sensolus backend at `/api/*`, so the kit's defaults just
+work:
+
+```jsx
+import { SntUiProvider, LocaleProvider, SntButton, SntCard } from '@sensolus/snt-agent-kit'
+import '@sensolus/snt-agent-kit/theme.css'
+import { messages } from './i18n'   // your app's translation keys
+
+function App() {
+  return (
+    <SntUiProvider>
+      <LocaleProvider messages={messages}>
+        <SntCard title="Hello">
+          <SntButton variant="primary">Click me</SntButton>
+        </SntCard>
+      </LocaleProvider>
+    </SntUiProvider>
+  )
+}
+```
+
+### Custom wiring (non-`/api/*` backends)
+
+`SntUiProvider` accepts overrides for any of the four backend calls and for
+navigation. Anything you omit falls back to the same-origin `/api/*` default.
+
+```jsx
+import { useNavigate } from 'react-router-dom'
+import { SntUiProvider } from '@sensolus/snt-agent-kit'
+
+function Shell({ children }) {
+  const navigate = useNavigate()
+  return (
+    <SntUiProvider
+      api={{
+        // Call the Sensolus public API directly with your own API key
+        fetchLoginInfo:  ()         => mySensolus.getLoginInfo(),
+        fetchGeozones:   (orgId)    => mySensolus.getGeozones(orgId),
+        geocode:         (q)        => mySensolus.geocode(q),
+        reverseGeocode:  (lat, lng) => mySensolus.reverseGeocode(lat, lng),
+      }}
+      navigate={navigate}  // optional: wire to react-router, Next, etc.
+    >
+      {children}
+    </SntUiProvider>
+  )
+}
+```
+
+#### `api` contract
+
+| Method | Signature | Used by |
+|--------|-----------|---------|
+| `fetchLoginInfo()` | `() => Promise<{ language, timezone, firstDayOfWeek, unitDistance, unitTemperature } \| null>` | `LocaleProvider` |
+| `fetchGeozones(orgId)` | `(string) => Promise<Geozone[]>` | `SntMap` (when `orgId` prop set) |
+| `geocode(query)` | `(string) => Promise<Array<{ name, lat, lng, boundingbox }>>` | `SntMap` (search box) |
+| `reverseGeocode(lat, lng)` | `(number, number) => Promise<{ displayName, address, lat, lng } \| null>` | reserved for future widgets |
+
+#### `navigate` contract
+
+`(to: string \| number) => void` — strings are routes (`'/orgs/123'`), `-1`
+means "back". Wire to `useNavigate()` from react-router-dom, the Next.js
+router, or omit to fall back to `window.history`.
+
+### SntMap
+
+Tile-provider keys are **required props** — the kit ships no keys. In a
+generated app they come from the backend's `/api/config` at runtime (via
+`AppConfigContext`), so one Docker image deploys across environments:
+
+```jsx
+const config = useAppConfig()
+
+<SntMap
+  mapboxKey={config.mapboxKey}
+  locationiqKey={config.locationiqKey}
+  devices={devices}
+  orgId={id}            // triggers api.fetchGeozones(orgId)
+/>
+```
+
+### Components
+
+| Component | Description |
+|-----------|-------------|
+| `SntUiProvider`, `useSntUi` | Inject backend `api` + `navigate` adapters |
+| `LocaleProvider`, `useLocale` | i18n / locale context (reads `api.fetchLoginInfo`, merges app `messages`) |
+| `formatShortDate`, `formatDateTime`, `formatNumber` | Locale-aware formatters |
+| `SntButton` | Primary button with variants |
+| `SntInput` | Text input (onChange receives value directly) |
+| `SntBadge` | Status badge with color variants |
+| `SntCard` | Card container |
+| `SntTable` | Sortable, paginated data table |
+| `SntSpinner`, `SntLoadingOverlay` | Loading indicators |
+| `SntToolbar`, `SntToolbarSpacer` | Toolbar layout |
+| `SntButtonGroup` | Segmented control |
+| `SntSelect` | Native select with Sensolus styling |
+| `SntPageHeader` | Page header (uses `navigate` from `SntUiProvider`) |
+| `SntTabs`, `SntTabPanel` | Tabbed views |
+| `SntDialog` | Modal dialog |
+| `SntSidepanel`, `SntFilterSection` | Slide-out side panel |
+| `SntSwitch` | Toggle switch |
+| `SntGrid`, `SntGridItem` | Responsive grid |
+| `SntSummaryStat` | Big-number summary tile |
+| `SntHistogram` | Time-bucketed histogram |
+| `SntCheckboxList` | Multi-select checkbox list |
+| `SntDateRangePicker` | Date range picker (locale-aware) |
+| `SntMap` | Leaflet map (Street/Satellite, geozones, device markers) |
+| `SntColors` | JavaScript color constants |
+
+The generated app includes a **Widgets** tab (`WidgetShowcase`) demonstrating
+every component live.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sensolus/create-snt-agent-app",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Scaffold a new Sensolus agent app: React frontend wired to @sensolus/snt-agent-kit + Flask API proxy backend.",
   "type": "module",
   "bin": {

package/template/package.json

@@ -15,7 +15,7 @@
     "url": "git+ssh://git@bitbucket.org/sensolus/{{APP_NAME}}.git"
   },
   "dependencies": {
-    "@sensolus/snt-agent-kit": "^0.2.0",
+    "@sensolus/snt-agent-kit": "^0.4.0",
     "react": "^19.2.3",
     "react-dom": "^19.2.3",
     "react-router-dom": "^7.1.1"

package/template/src/pages/OrganisationDetail.jsx

@@ -5,7 +5,7 @@ import {
   SntBadge,
   SntProgressBar,
   SntCard,
-  SntMap,
+  SntDeviceMap,
   SntSpinner,
 } from '@sensolus/snt-agent-kit'
 import { useLocale, formatNumber } from '../i18n'
@@ -214,7 +214,7 @@ export function OrganisationDetail() {
             <SntSpinner size="medium" />
           </div>
         ) : (
-          <SntMap
+          <SntDeviceMap
             mapboxKey={config.mapboxKey}
             locationiqKey={config.locationiqKey}
             height="500px"

package/template/src/pages/WidgetShowcase.jsx

@@ -14,6 +14,7 @@ import {
   SntInput,
   SntLoadingOverlay,
   SntMap,
+  SntDeviceLayer,
   SntProgressBar,
   SntSelect,
   SntSidepanel,
@@ -482,7 +483,7 @@ export function WidgetShowcase() {
       {/* ------------------------------------------------------------------ */}
       <Section
         title="SntMap"
-        description="Leaflet map with Street/Satellite layer toggle. Optionally renders geozones (by orgId or array) and device markers."
+        description="Base Leaflet map (street/satellite toggle, geocoder, zoom/scale). Compose with layer components — here, <SntDeviceLayer>."
       >
         <SntMap
           mapboxKey={config.mapboxKey}
@@ -490,14 +491,15 @@ export function WidgetShowcase() {
           height="320px"
           center={[50.85, 4.35]}
           zoom={6}
-          showGeozones={false}
-          showGeozoneSelector={false}
-          devices={[
-            { id: 'd1', name: 'Demo tracker A', lastLat: 50.8503, lastLng: 4.3517 },
-            { id: 'd2', name: 'Demo tracker B', lastLat: 51.2194, lastLng: 4.4025 },
-            { id: 'd3', name: 'Demo tracker C', lastLat: 51.0543, lastLng: 3.7174 },
-          ]}
-        />
+        >
+          <SntDeviceLayer
+            devices={[
+              { id: 'd1', name: 'Demo tracker A', lastLat: 50.8503, lastLng: 4.3517 },
+              { id: 'd2', name: 'Demo tracker B', lastLat: 51.2194, lastLng: 4.4025 },
+              { id: 'd3', name: 'Demo tracker C', lastLat: 51.0543, lastLng: 3.7174 },
+            ]}
+          />
+        </SntMap>
       </Section>
 
       {/* ------------------------------------------------------------------ */}