@telemetryos/cli 1.14.0 → 1.15.0

package/templates/vite-react-typescript-web/src/views/Render.tsx

@@ -1,24 +1,152 @@
-import { useUiScaleToSetRem } from '@telemetryos/sdk/react'
-import wordMarkPath from '../../assets/telemetryos-wordmark.svg'
-import { useSubtitleStoreState, useUiScaleStoreState } from '../hooks/store'
+/**
+ * Render view — the display content shown on physical signage devices.
+ *
+ * This template provides the shared scaffolding that every app needs:
+ *   - Theme system (8 themes with CSS custom properties)
+ *   - Responsive density tiers (full / comfortable / compact / minimal)
+ *   - Entrance animations (14 presets)
+ *   - Page padding and UI scale controls
+ *   - Background toggle (gradient or transparent for layering)
+ *   - Portrait/landscape detection
+ *
+ * Layout building blocks (CSS classes with entrance animation support):
+ *   .content-header   — top-level header bar (title + subtitle)
+ *   .content-card     — primary hero card with gradient background
+ *   .detail-grid      — grid container for detail cards
+ *   .detail-card      — small info cards (icon + value + label)
+ *   .content-section  — secondary section (footer bar, list, etc.)
+ *
+ * To build your app:
+ *   1. Add store hooks in hooks/store.ts and import them here.
+ *   2. Add their isLoading flags to `isStoreLoading`.
+ *   3. Replace the welcome content below with your layout using the classes above.
+ *   4. Use `density` and `isPortrait` to adapt your layout to available space.
+ */
+
+import { useUiScaleToSetRem, useUiAspectRatio } from '@telemetryos/sdk/react'
+import {
+  useThemeStoreState,
+  useUiScaleStoreState,
+  usePagePaddingStoreState,
+  useAnimationStoreState,
+  useShowBackgroundStoreState,
+  useSubtitleStoreState,
+} from '../hooks/store'
+import { themes, type ThemeName, type Theme } from '../themes'
 import './Render.css'
 
+/** Maps a Theme's color tokens to CSS custom properties consumed by Render.css. */
+function applyThemeVars(theme: Theme) {
+  const c = theme.colors
+  return {
+    '--bg-start': c.bgStart,
+    '--bg-mid': c.bgMid,
+    '--bg-end': c.bgEnd,
+    '--card-start': c.cardStart,
+    '--card-mid1': c.cardMid1,
+    '--card-mid2': c.cardMid2,
+    '--card-end': c.cardEnd,
+    '--card-shadow': c.cardShadow,
+    '--primary': c.primary,
+    '--secondary': c.secondary,
+    '--muted': c.muted,
+    '--accent': c.accent,
+    '--card-bg': c.cardBg,
+    '--card-border': c.cardBorder,
+    '--status-good': c.statusGood,
+    '--font-family': theme.fontFamily,
+  } as React.CSSProperties
+}
+
+/**
+ * Density tiers control spacing, font sizes, and which elements are visible.
+ * Determined by UI scale combined with aspect ratio (portrait needs more room).
+ */
+type Density = 'full' | 'comfortable' | 'compact' | 'minimal'
+
+function getDensity(uiScale: number, aspectRatio: number): Density {
+  const isPortrait = aspectRatio < 1
+  const pressure = uiScale * (isPortrait ? 1.2 : 1)
+  if (pressure < 1.4) return 'full'
+  if (pressure < 1.8) return 'comfortable'
+  if (pressure < 2.3) return 'compact'
+  return 'minimal'
+}
+
 export function Render() {
-  const [, uiScale] = useUiScaleStoreState()
+  // ── Store state ──────────────────────────────────────────────────────────
+  const [isLoadingScale, uiScale] = useUiScaleStoreState()
+  const [isLoadingPadding, pagePadding] = usePagePaddingStoreState()
+  const [isLoadingTheme, themeName] = useThemeStoreState()
+  const [isLoadingAnim, animation] = useAnimationStoreState()
+  const [isLoadingBg, showBackground] = useShowBackgroundStoreState()
+  const [isLoadingSubtitle, subtitle] = useSubtitleStoreState()
+  const aspectRatio = useUiAspectRatio()
+
+  // Drives rem scaling: html font-size = base * uiScale
   useUiScaleToSetRem(uiScale)
-  const [isLoading, subtitle] = useSubtitleStoreState()
 
+  // ── Loading gate — render nothing until all store values are available ───
+  const isStoreLoading = isLoadingScale || isLoadingPadding || isLoadingTheme || isLoadingAnim || isLoadingBg || isLoadingSubtitle
+  if (isStoreLoading) return null
+
+  // ── Derived layout state ─────────────────────────────────────────────────
+  const resolvedName = (Object.prototype.hasOwnProperty.call(themes, themeName) ? themeName : 'telemetryos') as ThemeName
+  const theme = themes[resolvedName]
+  const isPortrait = aspectRatio < 1
+  const density = getDensity(uiScale, aspectRatio)
+
+  // Themes that need special CSS overlays register their modifier class here.
+  const themeModifier: Record<string, string> = {
+    'telemetryos': 'render--telemetryos',
+    'neon-pulse': 'render--neon-pulse',
+    'solar-flare': 'render--solar-flare',
+    'emerald-matrix': 'render--emerald-matrix',
+    'arctic-aurora': 'render--arctic-aurora',
+    'the-matrix': 'render--the-matrix',
+    'plain-light': 'render--plain',
+    'plain-dark': 'render--plain',
+  }
+
+  const animClass = `anim--${animation}`
+  const layoutClasses = [
+    'render',
+    themeModifier[resolvedName] ?? '',
+    isPortrait ? 'render--portrait' : '',
+    `render--${density}`,
+    animClass,
+    showBackground ? '' : 'render--no-bg',
+  ].filter(Boolean).join(' ')
+
+  // ── Render ───────────────────────────────────────────────────────────────
   return (
-    <div className="render">
-      <img src={wordMarkPath} alt="TelemetryOS" className="render__logo" />
+    <div key={animation} className={layoutClasses} style={{ ...applyThemeVars(theme), '--page-padding': pagePadding } as React.CSSProperties}>
+      {/* Theme-specific background effects */}
+      {showBackground && resolvedName === 'telemetryos' && <div className="tos-sweep" />}
+      {showBackground && resolvedName === 'neon-pulse' && (
+        <div className="neon-pulse-bg">
+          <div className="neon-pulse-bg__orb" />
+          <div className="neon-pulse-bg__orb" />
+          <div className="neon-pulse-bg__orb" />
+        </div>
+      )}
+      {showBackground && resolvedName === 'solar-flare' && <div className="solar-flare-bg" />}
+      {showBackground && resolvedName === 'arctic-aurora' && <div className="arctic-aurora-bg" />}
+      {showBackground && resolvedName === 'the-matrix' && <div className="matrix-scanlines" />}
+
+      {/* ── Welcome content (replace with your app) ─────────────────────── */}
+
+      <img src={resolvedName === 'plain-light' ? '/assets/telemetryos-wordmark-dark.svg' : '/assets/telemetryos-wordmark.svg'} alt="TelemetryOS" className="render__logo" />
+
       <div className="render__hero">
-        {uiScale < 1.5 && (
+        {density !== 'minimal' && (
           <div className="render__hero-title">Welcome to TelemetryOS SDK</div>
         )}
-        <div className="render__hero-subtitle">{isLoading ? 'Loading...' : subtitle}</div>
+        <div className="render__hero-subtitle">{subtitle}</div>
       </div>
+
       <div className="render__docs-information">
-        {uiScale < 1.2 && (
+        {density === 'full' && (
           <>
             <div className="render__docs-information-title">
               To get started, edit the Render.tsx and Settings.tsx files
@@ -28,7 +156,7 @@ export function Render() {
             </div>
           </>
         )}
-        {uiScale < 1.35 && (
+        {(density === 'full' || density === 'comfortable') && (
           <a
             className="render__docs-information-button"
             href="https://docs.telemetryos.com/docs/sdk-getting-started"

package/templates/vite-react-typescript-web/src/views/Settings.tsx

@@ -1,72 +1,181 @@
+/**
+ * Settings view — configuration UI rendered inside the Studio admin portal.
+ *
+ * This view provides the standard appearance controls (theme, scale, padding,
+ * animation, background toggle) that ship with every app.
+ *
+ * To add app-specific settings:
+ *   1. Create store hooks in hooks/store.ts.
+ *   2. Import and destructure them here alongside the existing hooks.
+ *   3. Add their isLoading flags to the `isLoading` expression.
+ *   4. Wrap your controls in a <SettingsSection title="Your Section">.
+ *
+ * Available SDK settings components:
+ *   SettingsContainer, SettingsSection, SettingsDivider, SettingsHint,
+ *   SettingsField, SettingsLabel,
+ *   SettingsInputFrame, SettingsSelectFrame, SettingsSliderFrame,
+ *   SettingsSwitchFrame, SettingsSwitchLabel,
+ *   SettingsCheckboxFrame, SettingsCheckboxLabel
+ *
+ * SettingsSection is a collapsible accordion — use it to group related
+ * controls under a heading. It manages its own open/closed state.
+ * Always wrap new groups of settings in a SettingsSection.
+ */
+
 import {
   SettingsContainer,
-  SettingsDivider,
   SettingsField,
-  SettingsHeading,
+  SettingsHint,
   SettingsInputFrame,
   SettingsLabel,
+  SettingsSection,
+  SettingsSelectFrame,
   SettingsSliderFrame,
+  SettingsCheckboxFrame,
+  SettingsCheckboxLabel,
 } from '@telemetryos/sdk/react'
-import { useSubtitleStoreState, useUiScaleStoreState, useWelcomeMessageStoreState } from '../hooks/store'
+import {
+  useThemeStoreState,
+  useUiScaleStoreState,
+  usePagePaddingStoreState,
+  useAnimationStoreState,
+  useShowBackgroundStoreState,
+  useSubtitleStoreState,
+  useWelcomeMessageStoreState,
+} from '../hooks/store'
+import { themes } from '../themes'
 
 export function Settings() {
-  const [isLoadingUiScale, uiScale, setUiScale] = useUiScaleStoreState(5)
+  const [isLoadingTheme, themeName, setThemeName] = useThemeStoreState()
+  const [isLoadingScale, uiScale, setUiScale] = useUiScaleStoreState(5)
+  const [isLoadingPadding, pagePadding, setPagePadding] = usePagePaddingStoreState()
+  const [isLoadingAnim, animation, setAnimation] = useAnimationStoreState()
+  const [isLoadingBg, showBackground, setShowBackground] = useShowBackgroundStoreState()
   const [isLoadingSubtitle, subtitle, setSubtitle] = useSubtitleStoreState(250)
   const [isLoadingWelcome, welcomeMessage, setWelcomeMessage] = useWelcomeMessageStoreState(250)
 
+  const isLoading = isLoadingTheme || isLoadingScale || isLoadingPadding || isLoadingAnim || isLoadingBg
+
   return (
     <SettingsContainer>
+      {/* ── App-specific sections go here ─────────────────────────────── */}
+
+      <SettingsSection title="Content">
+        <SettingsField>
+          <SettingsLabel>Subtitle Text</SettingsLabel>
+          <SettingsInputFrame>
+            <input
+              type="text"
+              placeholder="Enter a subtitle..."
+              value={subtitle}
+              onChange={(e) => setSubtitle(e.target.value)}
+              disabled={isLoadingSubtitle}
+            />
+          </SettingsInputFrame>
+          <SettingsHint>Displayed below the welcome title on the render view</SettingsHint>
+        </SettingsField>
+      </SettingsSection>
 
-      <SettingsHeading>Render</SettingsHeading>
+      {/* ── Appearance (common to all apps) ────────────────────────────── */}
 
-      <SettingsField>
-        <SettingsLabel>UI Scale</SettingsLabel>
-        <SettingsSliderFrame>
-          <input
-            type="range"
-            min={1}
-            max={3}
-            step={0.01}
-            disabled={isLoadingUiScale}
-            value={uiScale}
-            onChange={(e) => setUiScale(parseFloat(e.target.value))}
-          />
-          <span>{uiScale}x</span>
-        </SettingsSliderFrame>
-      </SettingsField>
+      <SettingsSection title="Appearance">
+        <SettingsField>
+          <SettingsLabel>Theme</SettingsLabel>
+          <SettingsSelectFrame>
+            <select
+              disabled={isLoading}
+              value={themeName}
+              onChange={(e) => setThemeName(e.target.value)}
+            >
+              {Object.entries(themes).map(([key, theme]) => (
+                <option key={key} value={key}>{theme.label}</option>
+              ))}
+            </select>
+          </SettingsSelectFrame>
+        </SettingsField>
 
-      <SettingsDivider />
+        <SettingsField>
+          <SettingsLabel>UI Scale</SettingsLabel>
+          <SettingsSliderFrame>
+            <input
+              type="range"
+              min={1}
+              max={3}
+              step={0.01}
+              disabled={isLoading}
+              value={uiScale}
+              onChange={(e) => setUiScale(parseFloat(e.target.value))}
+            />
+            <span>{uiScale}x</span>
+          </SettingsSliderFrame>
+        </SettingsField>
 
-      <SettingsField>
-        <SettingsLabel>Subtitle Text</SettingsLabel>
-        <SettingsInputFrame>
-          <input
-            type="text"
-            placeholder='Some text for the subtitle...'
-            value={subtitle}
-            onChange={(e) => setSubtitle(e.target.value)}
-            disabled={isLoadingSubtitle}
-          />
-        </SettingsInputFrame>
-      </SettingsField>
+        <SettingsField>
+          <SettingsLabel>Padding</SettingsLabel>
+          <SettingsSliderFrame>
+            <input
+              type="range"
+              min={0}
+              max={3}
+              step={0.01}
+              disabled={isLoading}
+              value={pagePadding}
+              onChange={(e) => setPagePadding(parseFloat(e.target.value))}
+            />
+            <span>{pagePadding}x</span>
+          </SettingsSliderFrame>
+        </SettingsField>
 
-      <SettingsDivider />
+        <SettingsField>
+          <SettingsLabel>Entrance Animation</SettingsLabel>
+          <SettingsSelectFrame>
+            <select
+              disabled={isLoading}
+              value={animation}
+              onChange={(e) => setAnimation(e.target.value)}
+            >
+              <option value="fade-in">Fade</option>
+              <option value="fade">Fade Up</option>
+              <option value="flip">Flip</option>
+              <option value="unfold">Unfold</option>
+              <option value="scale">Scale</option>
+              <option value="zoom">Zoom</option>
+              <option value="slide">Slide</option>
+              <option value="drop">Drop</option>
+              <option value="bounce">Bounce</option>
+              <option value="rise">Rise</option>
+              <option value="blur">Blur</option>
+              <option value="glitch">Glitch</option>
+              <option value="none">None</option>
+            </select>
+          </SettingsSelectFrame>
+        </SettingsField>
 
-      <SettingsHeading>Web</SettingsHeading>
+        <SettingsField>
+          <SettingsCheckboxFrame>
+            <input type="checkbox" disabled={isLoading} checked={showBackground} onChange={(e) => setShowBackground(e.target.checked)} />
+            <SettingsCheckboxLabel>Show Background</SettingsCheckboxLabel>
+          </SettingsCheckboxFrame>
+          <SettingsHint>Uncheck for a transparent background</SettingsHint>
+        </SettingsField>
+      </SettingsSection>
 
-      <SettingsField>
-        <SettingsLabel>Welcome Message</SettingsLabel>
-        <SettingsInputFrame>
-          <input
-            type="text"
-            placeholder='A welcome message for the web view...'
-            value={welcomeMessage}
-            onChange={(e) => setWelcomeMessage(e.target.value)}
-            disabled={isLoadingWelcome}
-          />
-        </SettingsInputFrame>
-      </SettingsField>
+      {/* ── Web ────────────────────────────────────────────────────────── */}
 
+      <SettingsSection title="Web">
+        <SettingsField>
+          <SettingsLabel>Welcome Message</SettingsLabel>
+          <SettingsInputFrame>
+            <input
+              type="text"
+              placeholder='A welcome message for the web view...'
+              value={welcomeMessage}
+              onChange={(e) => setWelcomeMessage(e.target.value)}
+              disabled={isLoadingWelcome}
+            />
+          </SettingsInputFrame>
+        </SettingsField>
+      </SettingsSection>
     </SettingsContainer>
   )
 }