@sensolus/create-snt-agent-app 0.3.9 → 0.3.10

package/package.json

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

package/template/CLAUDE.md

@@ -89,10 +89,13 @@ import { SntButton, SntInput, SntBadge, SntTable } from '@sensolus/snt-agent-kit
 
 | Component | Description |
 |-----------|-------------|
-| `SntButton` | Primary button with variants (primary, secondary, success, danger, warning, info) |
+| `SntButton` | Button. Default (white, `secondary`) is the everyday primary action; use `emphasis` (dark blue) sparingly for the single most important action. Other variants: success, danger, warning, info. (`primary` is a deprecated alias for `emphasis`.) The first letter of the label is auto-capitalised. |
+| `SntIcon` | Named SVG icon (`export`, `download`, `edit`, `settings`, `pdf`, `report`, …). Inherits text color via `currentColor`; `size` to scale. |
+| `SntLink` | Brand-blue text link (underline on hover). `href` → `<a>`; `onClick` only → link-styled `<button>` for tertiary actions (e.g. a dialog's "Learn more"). |
 | `SntInput` | Text input (onChange receives value directly, not event) |
 | `SntBadge` | Status badge with color variants |
 | `SntCard` | Card container with optional image, title, badge |
+| `SntSection` | Titled page section (title + optional description + body) for grouping content. Use for page regions; `SntCard` is for content tiles. |
 | `SntTable` | Sortable, paginated data table |
 | `SntSpinner` | Loading spinner (sizes: small, medium, large) |
 | `SntLoadingOverlay` | Centered spinner with optional message |
@@ -119,14 +122,17 @@ import { SntButton, SntInput, SntBadge, SntTable } from '@sensolus/snt-agent-kit
 --snt-green: #39CB99;         /* Success */
 --snt-yellow: #FFCC66;        /* Warning */
 --snt-red: #E00000;           /* Danger */
---snt-infra: #00A6ED;         /* Info */
+--snt-ui-selected: #00A6ED;   /* Info */
 ```
 
 ### Widget Examples
 
 ```jsx
-// Button
-<SntButton variant="primary" onClick={handleClick}>Save</SntButton>
+// Button — the white default is the everyday primary action
+<SntButton onClick={handleClick}>Save</SntButton>
+
+// Use emphasis (dark blue) only for the single most important action on a screen
+<SntButton variant="emphasis" onClick={handleConfirm}>Confirm</SntButton>
 
 // Input
 <SntInput value={query} onChange={setQuery} placeholder="Search..." />
@@ -163,6 +169,21 @@ import { SntButton, SntInput, SntBadge, SntTable } from '@sensolus/snt-agent-kit
 2. **Import widgets** from `@sensolus/snt-agent-kit` - they're modular ES modules
 3. **Follow existing patterns** in `src/App.jsx` for examples
 4. **Reference the baseline** at `/sensolus/work/baseline/` for additional components not yet ported
+5. **Put the matching `SntIcon` in the primary button** whenever a mockup has an Export, Download, Edit, Settings, PDF, or Report action — e.g. `<SntButton icon={<SntIcon name="export" />}>Export</SntButton>`.
+6. **Button order in forms:** put the blue (`variant="emphasis"`) action **first** and the white (default) action **second** (e.g. Save before Cancel). This is a deliberate exception to the white-is-primary default and applies only to forms.
+7. **Overlay / dialog footer order (always):** blue (`variant="emphasis"`) first → white (default) second → link (`SntLink`) third, in that sequence — e.g. Delete, Cancel, Learn more. The tertiary action is always an `SntLink`, never a button.
+
+### Page layout rules
+
+These govern how widgets are composed on a page. Follow them when building or editing pages.
+
+1. **Page wrapper:** render page content inside `.page-root` — it carries the standard padding (24px top, 16px sides/bottom). Don't add your own outer padding.
+2. **Page header:** start every page with `SntPageHeader` for the title (and back button / actions). Don't hand-roll an `h1` + back chevron.
+3. **`SntSummaryStat` is never wrapped in a panel.** Place stat tiles directly in a `.summary-stats-row` on the page background — never inside an `SntCard`/panel. The row gaps give them enough white space to live on the page on their own. Non-clickable stats are flat white tiles (no border); clickable ones carry a grey fill + border, which is distinctive enough on its own — they don't need an enclosing card to set them apart. Reserve `SntCard` for content tiles further down.
+4. **Group sections with `SntSection`, content tiles with `SntCard`.** Use `SntSection` for titled page regions (a heading + body); use `SntCard` for individual content tiles within a region. Don't nest a section inside a card.
+5. **Avoid pie charts — use bar charts.** For part-to-whole or category comparisons, render a bar chart, not a pie/donut. Bars are easier to read and compare than angles/slices. Reserve pies for nothing by default.
+6. **Every chart axis has a label.** Both the x- and y-axis must carry a name (with units where relevant, e.g. "Distance (km)"). Never ship a chart with unlabelled axes.
+7. **Cards are auto-height; siblings in a row match the tallest.** A card sizes to its own content by default — don't set fixed heights. When cards sit side by side (e.g. an `SntGrid` row), they stretch to the height of the tallest card in that row so their tops and bottoms align (use `align-items: stretch`, the default for flex/grid rows). Don't hand-tune per-card heights to fake alignment.
 
 ## Internationalization (i18n)
 

package/template/README.md

@@ -462,7 +462,7 @@ Use CSS custom properties for consistent styling:
 --snt-green: #39CB99;            /* Success */
 --snt-yellow: #FFCC66;           /* Warning */
 --snt-red: #E00000;              /* Danger */
---snt-infra: #00A6ED;            /* Info */
+--snt-ui-selected: #00A6ED;      /* Info */
 
 /* Semantic Aliases (preferred) */
 --snt-color-primary: var(--snt-blue-darkest);

package/template/src/i18n/translations/de.js

@@ -11,6 +11,8 @@ export default {
   'overview.series.orgs': 'Organisationen',
   'overview.series.trackers': 'Tracker',
   'overview.series.users': 'Benutzer',
+  'overview.table.title': 'Verlauf der täglichen Momentaufnahmen',
+  'overview.table.date': 'Datum',
 
   // Common
 

package/template/src/i18n/translations/en.js

@@ -11,6 +11,8 @@ export default {
   'overview.series.orgs': 'Organisations',
   'overview.series.trackers': 'Trackers',
   'overview.series.users': 'Users',
+  'overview.table.title': 'Daily snapshot history',
+  'overview.table.date': 'Date',
 
   // Common
 

package/template/src/i18n/translations/es.js

@@ -11,6 +11,8 @@ export default {
   'overview.series.orgs': 'Organizaciones',
   'overview.series.trackers': 'Rastreadores',
   'overview.series.users': 'Usuarios',
+  'overview.table.title': 'Historial de instantáneas diarias',
+  'overview.table.date': 'Fecha',
 
   // Common
 

package/template/src/i18n/translations/fr.js

@@ -11,6 +11,8 @@ export default {
   'overview.series.orgs': 'Organisations',
   'overview.series.trackers': 'Traceurs',
   'overview.series.users': 'Utilisateurs',
+  'overview.table.title': 'Historique des instantanés quotidiens',
+  'overview.table.date': 'Date',
 
   // Common
 

package/template/src/i18n/translations/nl.js

@@ -11,6 +11,8 @@ export default {
   'overview.series.orgs': 'Organisaties',
   'overview.series.trackers': 'Trackers',
   'overview.series.users': 'Gebruikers',
+  'overview.table.title': 'Geschiedenis dagelijkse momentopname',
+  'overview.table.date': 'Datum',
 
   // Common
 

package/template/src/pages/Home.jsx

@@ -87,7 +87,6 @@ export function Home() {
       )}
       {activeTab === 'explore' && (
         <SntButton
-          variant="primary"
           onClick={() => orgListReloadRef.current?.()}
           disabled={orgListLoading || !authReady}
         >
@@ -147,6 +146,15 @@ export function Home() {
             gap: 8,
           }}
         >
+          {/* In forms the blue (emphasis) action comes first, white second —
+              an intentional exception to the white-is-primary guideline. */}
+          <SntButton
+            variant="emphasis"
+            onClick={submitApiKey}
+            disabled={submitting || !apiKeyInput.trim()}
+          >
+            {submitting ? t('common.loading') : t('common.save')}
+          </SntButton>
           {authReady && (
             <SntButton
               variant="secondary"
@@ -156,13 +164,6 @@ export function Home() {
               {t('common.cancel')}
             </SntButton>
           )}
-          <SntButton
-            variant="primary"
-            onClick={submitApiKey}
-            disabled={submitting || !apiKeyInput.trim()}
-          >
-            {submitting ? t('common.loading') : t('common.save')}
-          </SntButton>
         </div>
       </SntDialog>
     </div>

package/template/src/pages/Overview.jsx

@@ -1,5 +1,5 @@
 import { useEffect, useState } from 'react'
-import { SntCard, SntLoadingOverlay, SntSummaryStat } from '@sensolus/snt-agent-kit'
+import { SntCard, SntLoadingOverlay, SntSummaryStat, SntTable } from '@sensolus/snt-agent-kit'
 import { useLocale, formatNumber, formatShortDate } from '../i18n'
 
 const SERIES = [
@@ -192,6 +192,35 @@ export function Overview({ authReady }) {
             </div>
             <LineChart data={data} intlLocale={intlLocale} timezone={timezone} t={t} />
           </SntCard>
+
+          <SntCard title={t('overview.table.title')}>
+            <SntTable
+              data={[...data].reverse()}
+              rowKey="date"
+              columns={[
+                {
+                  key: 'date',
+                  header: t('overview.table.date'),
+                  render: (row) => formatShortDate(row.date, intlLocale, timezone),
+                },
+                {
+                  key: 'orgCount',
+                  header: t('overview.series.orgs'),
+                  render: (row) => formatNumber(row.orgCount, intlLocale),
+                },
+                {
+                  key: 'trackerTotal',
+                  header: t('overview.series.trackers'),
+                  render: (row) => formatNumber(row.trackerTotal, intlLocale),
+                },
+                {
+                  key: 'userTotal',
+                  header: t('overview.series.users'),
+                  render: (row) => formatNumber(row.userTotal, intlLocale),
+                },
+              ]}
+            />
+          </SntCard>
         </>
       )}
     </div>

package/template/src/pages/WidgetShowcase.jsx

@@ -6,6 +6,8 @@ import {
   SntCard,
   SntCheckboxList,
   SntColors,
+  SntIcon,
+  SNT_ICON_NAMES,
   SntDateRangePicker,
   SntDialog,
   SntGrid,
@@ -58,20 +60,20 @@ const BADGE_VARIANTS = [
   'info', 'light', 'dark', 'orange', 'salmon', 'purple', 'emerald',
 ]
 
-const BUTTON_VARIANTS = ['primary', 'secondary', 'success', 'danger', 'warning', 'info']
+const BUTTON_VARIANTS = ['secondary', 'emphasis', 'success', 'danger', 'warning', 'info']
 
 const TABLE_DATA = [
-  { id: 1, name: 'Alpha Logistics',  trackers: 142, status: 'ACTIVE'   },
-  { id: 2, name: 'Beta Transport',   trackers:  56, status: 'ACTIVE'   },
-  { id: 3, name: 'Gamma Couriers',   trackers:   8, status: 'INACTIVE' },
-  { id: 4, name: 'Delta Freight',    trackers: 231, status: 'ACTIVE'   },
-  { id: 5, name: 'Epsilon Shipping', trackers:  17, status: 'PENDING'  },
+  { id: 1, name: 'Alpha Logistics',  trackers: 142, status: 'Active'   },
+  { id: 2, name: 'Beta Transport',   trackers:  56, status: 'Active'   },
+  { id: 3, name: 'Gamma Couriers',   trackers:   8, status: 'Inactive' },
+  { id: 4, name: 'Delta Freight',    trackers: 231, status: 'Active'   },
+  { id: 5, name: 'Epsilon Shipping', trackers:  17, status: 'Pending'  },
 ]
 
 const STATUS_VARIANT = {
-  ACTIVE: 'success',
-  INACTIVE: 'secondary',
-  PENDING: 'warning',
+  Active: 'success',
+  Inactive: 'secondary',
+  Pending: 'warning',
 }
 
 const HISTOGRAM_BUCKETS = [
@@ -95,6 +97,7 @@ export function WidgetShowcase() {
   const [selectValue, setSelectValue] = useState('eu')
   const [groupValue, setGroupValue] = useState('cards')
   const [switchOn, setSwitchOn] = useState(true)
+  const [activeOnly, setActiveOnly] = useState(true)
   const [checkboxSelected, setCheckboxSelected] = useState(['Trackers', 'Geozones'])
   const [dateRange, setDateRange] = useState(() => getDefaultDateRange('week'))
   const [dialogOpen, setDialogOpen] = useState(false)
@@ -115,20 +118,50 @@ export function WidgetShowcase() {
       {/* ------------------------------------------------------------------ */}
       <Section
         title="SntButton"
-        description="Primary action button. Use variant to express intent (primary, success, danger, ...)."
+        description="The default (white) button is the everyday primary action — reach for it almost always. Use 'emphasis' (dark blue) sparingly for the single most important action on a screen."
       >
         <Example label="Variants">
           <div className="showcase-row">
             {BUTTON_VARIANTS.map((v) => (
-              <SntButton key={v} variant={v}>{v}</SntButton>
+              <SntButton key={v} variant={v}>{v === 'secondary' ? 'Primary' : v}</SntButton>
             ))}
           </div>
         </Example>
         <Example label="Disabled">
-          <SntButton variant="primary" disabled>Disabled</SntButton>
+          <SntButton disabled>Disabled</SntButton>
         </Example>
         <Example label="With icon">
-          <SntButton variant="primary" icon={<span>+</span>}>Add item</SntButton>
+          <SntButton icon={<SntIcon name="export" />}>Export</SntButton>
+        </Example>
+      </Section>
+
+      {/* ------------------------------------------------------------------ */}
+      <Section
+        title="SntIcon"
+        description="Named SVG icons from the Sensolus set. Icons inherit the surrounding text color (currentColor), so they adapt to button variants, links, etc. Set size to scale. For action buttons (export, download, settings, PDF, report) put the matching icon in the button."
+      >
+        <Example label="All icons">
+          <div className="showcase-row" style={{ alignItems: 'center', gap: 20 }}>
+            {SNT_ICON_NAMES.map((name) => (
+              <div
+                key={name}
+                style={{ display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 6 }}
+              >
+                <SntIcon name={name} size={24} title={name} />
+                <code style={{ fontSize: 12, color: 'var(--snt-grey)' }}>{name}</code>
+              </div>
+            ))}
+          </div>
+        </Example>
+        <Example label="In buttons">
+          <div className="showcase-row">
+            <SntButton icon={<SntIcon name="export" />}>Export</SntButton>
+            <SntButton icon={<SntIcon name="download" />}>Download</SntButton>
+            <SntButton icon={<SntIcon name="edit" />}>Edit</SntButton>
+            <SntButton icon={<SntIcon name="report" />}>Report</SntButton>
+            <SntButton icon={<SntIcon name="pdf" />}>PDF</SntButton>
+            <SntButton icon={<SntIcon name="settings" />}>Settings</SntButton>
+          </div>
         </Example>
       </Section>
 
@@ -145,7 +178,7 @@ export function WidgetShowcase() {
           </div>
         </Example>
         <Example label="Compact">
-          <SntBadge variant="success" text="ACTIVE" compact />
+          <SntBadge variant="success" text="Active" compact />
         </Example>
       </Section>
 
@@ -207,9 +240,9 @@ export function WidgetShowcase() {
             value={groupValue}
             onChange={setGroupValue}
             options={[
-              { value: 'cards', label: 'Cards' },
-              { value: 'table', label: 'Table' },
-              { value: 'map',   label: 'Map'   },
+              { value: 'cards', label: 'Cards', icon: <SntIcon name="card" /> },
+              { value: 'list',  label: 'List',  icon: <SntIcon name="list" /> },
+              { value: 'map',   label: 'Map',   icon: <SntIcon name="map" />  },
             ]}
           />
         </Example>
@@ -278,7 +311,7 @@ export function WidgetShowcase() {
             <SntCard
               title="Clickable"
               onClick={() => alert('Card clicked')}
-              titleButton={<SntButton variant="primary">Open</SntButton>}
+              titleButton={<SntButton>Open</SntButton>}
             >
               <p>onClick makes the whole card interactive.</p>
             </SntCard>
@@ -306,13 +339,13 @@ export function WidgetShowcase() {
         description="Horizontal row for grouping actions, with optional spacer."
       >
         <SntToolbar>
-          <SntButton variant="primary">Save</SntButton>
+          <SntButton variant="emphasis">Save</SntButton>
           <SntButton>Cancel</SntButton>
           <SntToolbarSpacer />
           <div style={{ width: 220 }}>
             <SntInput value="" onChange={() => {}} placeholder="Search..." />
           </div>
-          <SntButton variant="info">Filter</SntButton>
+          <SntButton icon={<SntIcon name="filter" />}>Filter</SntButton>
         </SntToolbar>
       </Section>
 
@@ -412,7 +445,7 @@ export function WidgetShowcase() {
           </div>
         </Example>
         <Example label="Loading overlay (toggle)">
-          <SntButton variant="primary" onClick={() => {
+          <SntButton onClick={() => {
             setShowOverlay(true)
             setTimeout(() => setShowOverlay(false), 1500)
           }}>
@@ -431,7 +464,7 @@ export function WidgetShowcase() {
         title="SntDialog"
         description="Modal dialog. open + onClose are controlled by the caller."
       >
-        <SntButton variant="primary" onClick={() => setDialogOpen(true)}>
+        <SntButton onClick={() => setDialogOpen(true)}>
           Open dialog
         </SntButton>
         <SntDialog
@@ -442,8 +475,8 @@ export function WidgetShowcase() {
         >
           <p>This is a small modal dialog. Click the backdrop or × to close.</p>
           <div style={{ marginTop: 16, display: 'flex', justifyContent: 'flex-end', gap: 8 }}>
+            <SntButton variant="emphasis" onClick={() => setDialogOpen(false)}>OK</SntButton>
             <SntButton onClick={() => setDialogOpen(false)}>Cancel</SntButton>
-            <SntButton variant="primary" onClick={() => setDialogOpen(false)}>OK</SntButton>
           </div>
         </SntDialog>
       </Section>
@@ -461,7 +494,7 @@ export function WidgetShowcase() {
             width={240}
           >
             <SntFilterSection label="Status">
-              <SntSwitch checked onChange={() => {}} label="Active only" />
+              <SntSwitch checked={activeOnly} onChange={setActiveOnly} label="Active only" />
             </SntFilterSection>
             <SntFilterSection label="Region">
               <SntSelect