@bridgeline-digital/hawk-app-cli 0.0.0-stage → 0.1.0-dev.20261020202308

package/templates/react/src/App.tsx

@@ -0,0 +1,83 @@
+import { HawkApiError, type AnalyticsReportRow } from '@bridgeline-digital/hawk-app-bridge/client';
+import { createFormat } from '@bridgeline-digital/hawk-app-ui/elements';
+import { useEffect, useMemo, useState } from 'react';
+import { useHawkApp } from './useHawkApp';
+
+/**
+ * Starter screen: the context from the host and one real data call, shown with the UI kit (Spark's look: the kit's
+ * stylesheet and its elements, <hawk-kpi> and <hawk-column-chart>). Replace it with your app. Data comes only through
+ * the bridge: no API keys in the app.
+ */
+export function App() {
+    const hawk = useHawkApp();
+    const [rows, setRows] = useState<AnalyticsReportRow<'searches'>[] | null>(null);
+    const [error, setError] = useState<string | null>(null);
+
+    const app = hawk.status === 'ready' ? hawk.app : undefined;
+    const context = hawk.status === 'ready' ? hawk.context : undefined;
+    const format = useMemo(() => createFormat(context?.locale), [context?.locale]);
+
+    // Reload whenever the user changes the date range or engine in the host.
+    useEffect(() => {
+        if (!app || !context) return;
+        let current = true;
+        setRows(null);
+        setError(null);
+        const filters = context.engine ? [{ member: 'engine_id' as const, operator: 'equals', values: [context.engine.id] }] : undefined;
+        app.analytics
+            .report('searches', { filters, limit: 1000 }) // dates default to the host's date range
+            .then((report) => current && setRows(report.data))
+            .catch((e: unknown) => current && setError(e instanceof HawkApiError ? `${e.message}${e.code ? ` (${e.code})` : ''}` : String(e)));
+        return () => {
+            current = false;
+        };
+    }, [app, context?.dateRange?.from, context?.dateRange?.to, context?.engine?.id]);
+
+    // One column per day (a day can have a row per engine).
+    const days = useMemo(() => {
+        const byDay = new Map<string, number>();
+        for (const row of rows ?? []) byDay.set(row.search_date, (byDay.get(row.search_date) ?? 0) + row.search_count);
+        return [...byDay].sort(([a], [b]) => a.localeCompare(b)).map(([date, value]) => ({ label: format.date(date, { year: false }), value }));
+    }, [rows, format]);
+
+    if (hawk.status === 'connecting') return <span className="hawk-spinner" aria-label="Connecting" />;
+    if (hawk.status === 'error') return <div className="hawk-notice is-error">{hawk.message}</div>;
+
+    const total = days.reduce((sum, d) => sum + d.value, 0);
+    const { tenant, engine, dateRange } = hawk.context;
+    return (
+        <main className="hawk-stack">
+            <div>
+                <h1>__NAME__</h1>
+                <p className="hawk-muted">
+                    Client {tenant.clientId}
+                    {engine ? ` · ${engine.name ?? `Engine ${engine.id}`}` : ''}
+                    {dateRange ? ` · ${format.date(dateRange.from)} – ${format.date(dateRange.to)}` : ''}
+                </p>
+            </div>
+
+            {error && <div className="hawk-notice is-error">{error}</div>}
+
+            <div className="hawk-kpi-row">
+                <hawk-kpi label="Searches" value={rows ? format.integer(total) : ''} loading={rows ? undefined : ''} highlight="" />
+                <hawk-kpi label="Searches per day" value={rows ? format.integer(days.length ? total / days.length : 0) : ''} loading={rows ? undefined : ''} hint={rows ? `over ${days.length} days` : undefined} />
+            </div>
+
+            <section className="hawk-section">
+                <div className="hawk-section-header">
+                    <div>
+                        <h2 className="hawk-section-title">Searches per day</h2>
+                        <p className="hawk-section-subtitle">In the host&apos;s date range. Hover a column for its number.</p>
+                    </div>
+                </div>
+                {rows ? <hawk-column-chart label="Searches per day" value-format="integer" columns={days} /> : <span className="hawk-spinner" />}
+            </section>
+
+            <div>
+                <button className="hawk-button" onClick={() => hawk.app.toast('Hello from __NAME__!', 'success')}>
+                    Say hello
+                </button>
+            </div>
+        </main>
+    );
+}

package/templates/react/src/hawk-elements.d.ts

@@ -0,0 +1,10 @@
+// The UI kit's custom elements in JSX (<hawk-kpi>, <hawk-data-table>, <hawk-bar-list>, <hawk-column-chart>).
+import type { HawkElementTags } from '@bridgeline-digital/hawk-app-ui/elements';
+
+declare module 'react' {
+    // eslint-disable-next-line @typescript-eslint/no-namespace
+    namespace JSX {
+        // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+        interface IntrinsicElements extends HawkElementTags {}
+    }
+}

package/templates/react/src/main.tsx

@@ -0,0 +1,13 @@
+import { StrictMode } from 'react';
+import { createRoot } from 'react-dom/client';
+// The UI kit: Spark's look (stylesheet, with Montserrat) and its elements (<hawk-kpi>, <hawk-data-table>, …).
+import '@bridgeline-digital/hawk-app-ui/css';
+import '@bridgeline-digital/hawk-app-ui/elements';
+import { App } from './App';
+import './styles.css';
+
+createRoot(document.getElementById('root')!).render(
+    <StrictMode>
+        <App />
+    </StrictMode>,
+);

package/templates/react/src/styles.css

@@ -0,0 +1,5 @@
+/*
+ * Your app's own styles. Spark's look comes from the UI kit's stylesheet (imported in main.tsx): its hawk-* classes
+ * (hawk-section, hawk-button, hawk-notice, hawk-table, …) and --hawk-ui-* variables, which follow the host's colors
+ * and light or dark mode. Use those before adding your own.
+ */

package/templates/react/src/useHawkApp.ts

@@ -0,0 +1,44 @@
+import { createApp, type HawkApp, type HawkAppContext } from '@bridgeline-digital/hawk-app-bridge/client';
+import { useEffect, useState } from 'react';
+
+/** Shown when the app is opened directly instead of inside a host. */
+function notEmbeddedMessage(): string {
+    return `Open this app from the Apps page in HawkSearch. Developing locally? Add ?devUrl=${window.location.href} to the app's address in HawkSearch.`;
+}
+
+export type HawkAppState =
+    | { status: 'connecting' }
+    | { status: 'ready'; app: HawkApp; context: HawkAppContext }
+    | { status: 'error'; message: string };
+
+/** Connects to the host (the HawkSearch dashboard / Spark) once and keeps the context (client, engine, dates, theme) current. */
+export function useHawkApp(): HawkAppState {
+    const [state, setState] = useState<HawkAppState>({ status: 'connecting' });
+
+    useEffect(() => {
+        let app: HawkApp | undefined;
+        let cancelled = false;
+
+        createApp({ autoResize: true })
+            .then((connected) => {
+                if (cancelled) return connected.destroy();
+                app = connected;
+                setState({ status: 'ready', app: connected, context: connected.context });
+                connected.onContextChange((context) => setState({ status: 'ready', app: connected, context }));
+            })
+            .catch((error: { code?: string; message?: string }) => {
+                if (cancelled) return;
+                setState({
+                    status: 'error',
+                    message: error.code === 'not_embedded' ? notEmbeddedMessage() : `Could not connect to the host: ${error.message}`,
+                });
+            });
+
+        return () => {
+            cancelled = true;
+            app?.destroy();
+        };
+    }, []);
+
+    return state;
+}

package/templates/react/src/vite-env.d.ts

@@ -0,0 +1 @@
+/// <reference types="vite/client" />

package/templates/react/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "jsx": "react-jsx",
+    "strict": true,
+    "noUnusedLocals": true,
+    "skipLibCheck": true,
+    "isolatedModules": true,
+    "noEmit": true,
+    "types": ["vite/client", "node"]
+  },
+  "include": ["src", "vite.config.ts"]
+}

package/templates/react/vite.config.ts

@@ -0,0 +1,11 @@
+import react from '@vitejs/plugin-react';
+import { defineConfig } from 'vite';
+
+// Each deploy is served from the apps CDN at /<slug>/v<n>/, so every asset URL needs that prefix.
+// `hawk-app deploy` builds with HAWK_APP_BASE_PATH=/<slug>/v<n>; local dev uses /<slug>/.
+export default defineConfig({
+    base: `${process.env.HAWK_APP_BASE_PATH ?? '/__SLUG__'}/`,
+    plugins: [react()],
+    // Port 3100: the dev platform accepts data calls from localhost:3100-3103 (HawkSearch dev mode, ?devUrl=).
+    server: { port: 3100, strictPort: true },
+});

package/templates/vanilla/package.json

@@ -0,0 +1,15 @@
+{
+  "name": "__SLUG__",
+  "version": "0.1.0",
+  "private": true,
+  "scripts": {
+    "dev": "serve public -l 3100",
+    "app:dev": "hawk-app dev",
+    "app:deploy": "hawk-app deploy",
+    "app:audit": "npm audit --omit=dev --audit-level=high"
+  },
+  "devDependencies": {
+    "@bridgeline-digital/hawk-app-cli": "^__CLI_VERSION__",
+    "serve": "^14.2.4"
+  }
+}

package/templates/vanilla/public/app.js

@@ -0,0 +1,59 @@
+// No build step: the bridge and the UI kit's elements are loaded straight from the CDN (the kit's stylesheet is in
+// index.html). Data comes only through the bridge (no API keys).
+import { createApp } from 'https://cdn.jsdelivr.net/npm/@bridgeline-digital/hawk-app-bridge@0.1/dist/client/index.js';
+import { createFormat } from 'https://cdn.jsdelivr.net/npm/@bridgeline-digital/hawk-app-ui@0.1/dist/elements/index.js';
+
+const $ = (id) => document.getElementById(id);
+
+async function loadSearches(app) {
+    const { engine, locale } = app.context;
+    const format = createFormat(locale);
+    $('total').setAttribute('loading', '');
+    $('per-day').setAttribute('loading', '');
+    $('error').hidden = true;
+    try {
+        const filters = engine ? [{ member: 'engine_id', operator: 'equals', values: [engine.id] }] : undefined;
+        const report = await app.analytics.report('searches', { filters, limit: 1000 }); // dates default to the host's range
+        // One column per day (a day can have a row per engine).
+        const byDay = new Map();
+        for (const row of report.data) byDay.set(row.search_date, (byDay.get(row.search_date) ?? 0) + row.search_count);
+        const days = [...byDay].sort(([a], [b]) => a.localeCompare(b)).map(([date, value]) => ({ label: format.date(date, { year: false }), value }));
+        const total = days.reduce((sum, d) => sum + d.value, 0);
+
+        $('total').setAttribute('value', format.integer(total));
+        $('per-day').setAttribute('value', format.integer(days.length ? total / days.length : 0));
+        $('per-day').setAttribute('hint', `over ${days.length} days`);
+        $('chart').columns = days;
+    } catch (error) {
+        $('error').textContent = `${error.message}${error.code ? ` (${error.code})` : ''}`;
+        $('error').hidden = false;
+    } finally {
+        $('total').removeAttribute('loading');
+        $('per-day').removeAttribute('loading');
+    }
+}
+
+function showContext({ tenant, engine, dateRange, locale }) {
+    const format = createFormat(locale);
+    $('context').textContent = [
+        `Client ${tenant.clientId}`,
+        engine && (engine.name ?? `Engine ${engine.id}`),
+        dateRange && `${format.date(dateRange.from)} – ${format.date(dateRange.to)}`,
+    ]
+        .filter(Boolean)
+        .join(' · ');
+}
+
+try {
+    const app = await createApp({ autoResize: true });
+    showContext(app.context);
+    loadSearches(app);
+    app.onContextChange((context) => {
+        showContext(context);
+        loadSearches(app);
+    });
+    $('hello').onclick = () => app.toast('Hello from __NAME__!', 'success');
+} catch (error) {
+    $('context').textContent = error.code === 'not_embedded' ? `Open this app from the Apps page in HawkSearch. Developing locally? Add ?devUrl=${location.href} to the app's address in HawkSearch.` : `Could not connect: ${error.message}`;
+    $('context').className = 'hawk-error-text';
+}

package/templates/vanilla/public/index.html

@@ -0,0 +1,37 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="UTF-8" />
+        <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+        <title>__NAME__</title>
+        <!-- The UI kit: Spark's look (with Montserrat), in the host's colors and mode. Same version as the bridge. -->
+        <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/@bridgeline-digital/hawk-app-ui@0.1/dist/css/hawk.css" />
+        <link rel="stylesheet" href="styles.css" />
+    </head>
+    <body>
+        <main class="hawk-stack">
+            <div>
+                <h1>__NAME__</h1>
+                <p id="context" class="hawk-muted">Connecting…</p>
+            </div>
+            <div id="error" class="hawk-notice is-error" hidden></div>
+            <div class="hawk-kpi-row">
+                <hawk-kpi id="total" label="Searches" highlight loading></hawk-kpi>
+                <hawk-kpi id="per-day" label="Searches per day" loading></hawk-kpi>
+            </div>
+            <section class="hawk-section">
+                <div class="hawk-section-header">
+                    <div>
+                        <h2 class="hawk-section-title">Searches per day</h2>
+                        <p class="hawk-section-subtitle">In the host's date range. Hover a column for its number.</p>
+                    </div>
+                </div>
+                <hawk-column-chart id="chart" label="Searches per day" value-format="integer"></hawk-column-chart>
+            </section>
+            <div>
+                <button id="hello" class="hawk-button">Say hello</button>
+            </div>
+        </main>
+        <script type="module" src="app.js"></script>
+    </body>
+</html>

package/templates/vanilla/public/styles.css

@@ -0,0 +1,5 @@
+/*
+ * Your app's own styles. Spark's look comes from the UI kit's stylesheet (linked in index.html): its hawk-* classes
+ * (hawk-section, hawk-button, hawk-notice, hawk-table, …) and --hawk-ui-* variables, which follow the host's colors
+ * and light or dark mode. Use those before adding your own.
+ */