@databricks/appkit-ui 0.0.2

package/dist/styles.css

@@ -0,0 +1,425 @@
+@import "tailwindcss";
+@import "tw-animate-css";
+@source "./react";
+
+:root {
+  --radius: 0.625rem;
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.141 0.005 285.823);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.141 0.005 285.823);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.141 0.005 285.823);
+  --primary: oklch(0.21 0.006 285.885);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.967 0.001 286.375);
+  --secondary-foreground: oklch(0.21 0.006 285.885);
+  --muted: oklch(0.967 0.001 286.375);
+  --muted-foreground: oklch(0.552 0.016 285.938);
+  --accent: oklch(0.967 0.001 286.375);
+  --accent-foreground: oklch(0.21 0.006 285.885);
+  --destructive: oklch(0.577 0.245 27.325);
+  --destructive-foreground: oklch(0.985 0 0);
+  --success: oklch(0.603 0.135 166.892);
+  --success-foreground: oklch(1 0 0);
+  --warning: oklch(0.795 0.157 78.748);
+  --warning-foreground: oklch(0.199 0.027 238.732);
+  --border: oklch(0.92 0.004 286.32);
+  --input: oklch(0.92 0.004 286.32);
+  --ring: oklch(0.705 0.015 286.067);
+  /* ========================================
+     CATEGORICAL - Distinct unordered categories
+     Use for: bar charts, pie charts, legends
+     ======================================== */
+  --chart-cat-1: hsla(221, 83%, 53%, 1); /* Blue */
+  --chart-cat-2: hsla(160, 60%, 45%, 1); /* Teal */
+  --chart-cat-3: hsla(291, 47%, 51%, 1); /* Purple */
+  --chart-cat-4: hsla(35, 92%, 55%, 1); /* Amber */
+  --chart-cat-5: hsla(349, 72%, 52%, 1); /* Rose */
+  --chart-cat-6: hsla(189, 75%, 42%, 1); /* Cyan */
+  --chart-cat-7: hsla(271, 55%, 60%, 1); /* Lavender */
+  --chart-cat-8: hsla(142, 55%, 45%, 1); /* Emerald */
+
+  /* ========================================
+     SEQUENTIAL - Ordered magnitude (low → high)
+     Use for: heatmaps, density, choropleth
+     ======================================== */
+  --chart-seq-1: hsla(221, 70%, 94%, 1); /* Lightest */
+  --chart-seq-2: hsla(221, 72%, 85%, 1);
+  --chart-seq-3: hsla(221, 74%, 74%, 1);
+  --chart-seq-4: hsla(221, 76%, 63%, 1);
+  --chart-seq-5: hsla(221, 78%, 52%, 1);
+  --chart-seq-6: hsla(221, 80%, 42%, 1);
+  --chart-seq-7: hsla(221, 82%, 32%, 1);
+  --chart-seq-8: hsla(221, 84%, 24%, 1); /* Darkest */
+
+  /* ========================================
+     DIVERGING - Meaningful center point
+     Use for: profit/loss, correlation, deviation
+     1-4: negative (blue), 5-8: positive (red)
+     ======================================== */
+  --chart-div-1: hsla(221, 80%, 35%, 1); /* Strong negative */
+  --chart-div-2: hsla(221, 70%, 50%, 1);
+  --chart-div-3: hsla(221, 55%, 65%, 1);
+  --chart-div-4: hsla(221, 35%, 82%, 1); /* Weak negative */
+  --chart-div-5: hsla(10, 35%, 82%, 1); /* Weak positive */
+  --chart-div-6: hsla(10, 60%, 65%, 1);
+  --chart-div-7: hsla(10, 72%, 50%, 1);
+  --chart-div-8: hsla(10, 80%, 40%, 1); /* Strong positive */
+
+  /* Legacy aliases (for backwards compatibility) */
+  --chart-1: var(--chart-cat-1);
+  --chart-2: var(--chart-cat-2);
+  --chart-3: var(--chart-cat-3);
+  --chart-4: var(--chart-cat-4);
+  --chart-5: var(--chart-cat-5);
+  --chart-6: var(--chart-cat-6);
+  --chart-7: var(--chart-cat-7);
+  --chart-8: var(--chart-cat-8);
+  --sidebar: oklch(0.985 0 0);
+  --sidebar-foreground: oklch(0.141 0.005 285.823);
+  --sidebar-primary: oklch(0.21 0.006 285.885);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.967 0.001 286.375);
+  --sidebar-accent-foreground: oklch(0.21 0.006 285.885);
+  --sidebar-border: oklch(0.92 0.004 286.32);
+  --sidebar-ring: oklch(0.705 0.015 286.067);
+}
+
+/* Dark theme via class (takes precedence over media query) */
+.dark {
+  --background: oklch(0.141 0.005 285.823);
+  --foreground: oklch(0.985 0 0);
+  --card: oklch(0.21 0.006 285.885);
+  --card-foreground: oklch(0.985 0 0);
+  --popover: oklch(0.21 0.006 285.885);
+  --popover-foreground: oklch(0.985 0 0);
+  --primary: oklch(0.92 0.004 286.32);
+  --primary-foreground: oklch(0.21 0.006 285.885);
+  --secondary: oklch(0.274 0.006 286.033);
+  --secondary-foreground: oklch(0.985 0 0);
+  --muted: oklch(0.274 0.006 286.033);
+  --muted-foreground: oklch(0.705 0.015 286.067);
+  --accent: oklch(0.274 0.006 286.033);
+  --accent-foreground: oklch(0.985 0 0);
+  --destructive: oklch(0.704 0.191 22.216);
+  --destructive-foreground: oklch(0.985 0 0);
+  --success: oklch(0.67 0.12 167);
+  --success-foreground: oklch(1 0 0);
+  --warning: oklch(0.83 0.165 85);
+  --warning-foreground: oklch(0.199 0.027 238.732);
+  --border: oklch(1 0 0 / 10%);
+  --input: oklch(1 0 0 / 15%);
+  --ring: oklch(0.552 0.016 285.938);
+  --chart-1: oklch(0.488 0.243 264.376);
+  --chart-2: oklch(0.696 0.17 162.48);
+  --chart-3: oklch(0.769 0.188 70.08);
+  --chart-4: oklch(0.627 0.265 303.9);
+  --chart-5: oklch(0.645 0.246 16.439);
+  --sidebar: oklch(0.21 0.006 285.885);
+  --sidebar-foreground: oklch(0.985 0 0);
+  --sidebar-primary: oklch(0.488 0.243 264.376);
+  --sidebar-primary-foreground: oklch(0.985 0 0);
+  --sidebar-accent: oklch(0.274 0.006 286.033);
+  --sidebar-accent-foreground: oklch(0.985 0 0);
+  --sidebar-border: oklch(1 0 0 / 10%);
+  --sidebar-ring: oklch(0.552 0.016 285.938);
+}
+
+/* Dark theme via media query (fallback when no class is set) */
+@media (prefers-color-scheme: dark) {
+  :root:not(.light) {
+    --background: oklch(0.141 0.005 285.823);
+    --foreground: oklch(0.985 0 0);
+    --card: oklch(0.21 0.006 285.885);
+    --card-foreground: oklch(0.985 0 0);
+    --popover: oklch(0.21 0.006 285.885);
+    --popover-foreground: oklch(0.985 0 0);
+    --primary: oklch(0.92 0.004 286.32);
+    --primary-foreground: oklch(0.21 0.006 285.885);
+    --secondary: oklch(0.274 0.006 286.033);
+    --secondary-foreground: oklch(0.985 0 0);
+    --muted: oklch(0.274 0.006 286.033);
+    --muted-foreground: oklch(0.705 0.015 286.067);
+    --accent: oklch(0.274 0.006 286.033);
+    --accent-foreground: oklch(0.985 0 0);
+    --destructive: oklch(0.704 0.191 22.216);
+    --destructive-foreground: oklch(0.985 0 0);
+    --success: oklch(0.67 0.12 167);
+    --success-foreground: oklch(1 0 0);
+    --warning: oklch(0.83 0.165 85);
+    --warning-foreground: oklch(0.199 0.027 238.732);
+    --border: oklch(1 0 0 / 10%);
+    --input: oklch(1 0 0 / 15%);
+    --ring: oklch(0.552 0.016 285.938);
+    /* ========================================
+       CATEGORICAL - Distinct unordered categories
+       ======================================== */
+    --chart-cat-1: hsla(217, 91%, 65%, 1); /* Blue */
+    --chart-cat-2: hsla(160, 65%, 55%, 1); /* Teal */
+    --chart-cat-3: hsla(291, 60%, 65%, 1); /* Purple */
+    --chart-cat-4: hsla(38, 95%, 60%, 1); /* Amber */
+    --chart-cat-5: hsla(349, 80%, 62%, 1); /* Rose */
+    --chart-cat-6: hsla(189, 85%, 52%, 1); /* Cyan */
+    --chart-cat-7: hsla(271, 65%, 70%, 1); /* Lavender */
+    --chart-cat-8: hsla(142, 60%, 55%, 1); /* Emerald */
+
+    /* ========================================
+       SEQUENTIAL - Ordered magnitude (low → high)
+       ======================================== */
+    --chart-seq-1: hsla(
+      217,
+      50%,
+      25%,
+      1
+    ); /* Darkest (inverted for dark mode) */
+    --chart-seq-2: hsla(217, 55%, 35%, 1);
+    --chart-seq-3: hsla(217, 60%, 45%, 1);
+    --chart-seq-4: hsla(217, 65%, 55%, 1);
+    --chart-seq-5: hsla(217, 70%, 62%, 1);
+    --chart-seq-6: hsla(217, 75%, 70%, 1);
+    --chart-seq-7: hsla(217, 80%, 78%, 1);
+    --chart-seq-8: hsla(217, 85%, 88%, 1); /* Lightest */
+
+    /* ========================================
+       DIVERGING - Meaningful center point
+       ======================================== */
+    --chart-div-1: hsla(217, 85%, 70%, 1); /* Strong negative (blue) */
+    --chart-div-2: hsla(217, 70%, 60%, 1);
+    --chart-div-3: hsla(217, 50%, 50%, 1);
+    --chart-div-4: hsla(217, 25%, 40%, 1); /* Weak negative */
+    --chart-div-5: hsla(10, 25%, 40%, 1); /* Weak positive */
+    --chart-div-6: hsla(10, 55%, 50%, 1);
+    --chart-div-7: hsla(10, 70%, 58%, 1);
+    --chart-div-8: hsla(10, 80%, 65%, 1); /* Strong positive (red) */
+
+    /* Legacy aliases */
+    --chart-1: var(--chart-cat-1);
+    --chart-2: var(--chart-cat-2);
+    --chart-3: var(--chart-cat-3);
+    --chart-4: var(--chart-cat-4);
+    --chart-5: var(--chart-cat-5);
+    --chart-6: var(--chart-cat-6);
+    --chart-7: var(--chart-cat-7);
+    --chart-8: var(--chart-cat-8);
+    --sidebar: oklch(0.21 0.006 285.885);
+    --sidebar-foreground: oklch(0.985 0 0);
+    --sidebar-primary: oklch(0.488 0.243 264.376);
+    --sidebar-primary-foreground: oklch(0.985 0 0);
+    --sidebar-accent: oklch(0.274 0.006 286.033);
+    --sidebar-accent-foreground: oklch(0.985 0 0);
+    --sidebar-border: oklch(1 0 0 / 10%);
+    --sidebar-ring: oklch(0.552 0.016 285.938);
+  }
+}
+
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--destructive-foreground);
+  --color-success: var(--success);
+  --color-success-foreground: var(--success-foreground);
+  --color-warning: var(--warning);
+  --color-warning-foreground: var(--warning-foreground);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  /* Legacy chart colors (aliased to categorical) */
+  --color-chart-1: var(--chart-1);
+  --color-chart-2: var(--chart-2);
+  --color-chart-3: var(--chart-3);
+  --color-chart-4: var(--chart-4);
+  --color-chart-5: var(--chart-5);
+  --color-chart-6: var(--chart-6);
+  --color-chart-7: var(--chart-7);
+  --color-chart-8: var(--chart-8);
+
+  /* Categorical colors */
+  --color-chart-cat-1: var(--chart-cat-1);
+  --color-chart-cat-2: var(--chart-cat-2);
+  --color-chart-cat-3: var(--chart-cat-3);
+  --color-chart-cat-4: var(--chart-cat-4);
+  --color-chart-cat-5: var(--chart-cat-5);
+  --color-chart-cat-6: var(--chart-cat-6);
+  --color-chart-cat-7: var(--chart-cat-7);
+  --color-chart-cat-8: var(--chart-cat-8);
+
+  /* Sequential colors */
+  --color-chart-seq-1: var(--chart-seq-1);
+  --color-chart-seq-2: var(--chart-seq-2);
+  --color-chart-seq-3: var(--chart-seq-3);
+  --color-chart-seq-4: var(--chart-seq-4);
+  --color-chart-seq-5: var(--chart-seq-5);
+  --color-chart-seq-6: var(--chart-seq-6);
+  --color-chart-seq-7: var(--chart-seq-7);
+  --color-chart-seq-8: var(--chart-seq-8);
+
+  /* Diverging colors */
+  --color-chart-div-1: var(--chart-div-1);
+  --color-chart-div-2: var(--chart-div-2);
+  --color-chart-div-3: var(--chart-div-3);
+  --color-chart-div-4: var(--chart-div-4);
+  --color-chart-div-5: var(--chart-div-5);
+  --color-chart-div-6: var(--chart-div-6);
+  --color-chart-div-7: var(--chart-div-7);
+  --color-chart-div-8: var(--chart-div-8);
+  --color-sidebar: var(--sidebar);
+  --color-sidebar-foreground: var(--sidebar-foreground);
+  --color-sidebar-primary: var(--sidebar-primary);
+  --color-sidebar-primary-foreground: var(--sidebar-primary-foreground);
+  --color-sidebar-accent: var(--sidebar-accent);
+  --color-sidebar-accent-foreground: var(--sidebar-accent-foreground);
+  --color-sidebar-border: var(--sidebar-border);
+  --color-sidebar-ring: var(--sidebar-ring);
+  --radius: var(--radius);
+}
+
+@layer base {
+  * {
+    border-color: var(--border);
+  }
+
+  html {
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+    text-rendering: optimizeLegibility;
+  }
+
+  body {
+    background-color: var(--background);
+    color: var(--foreground);
+    font-feature-settings:
+      "rlig" 1,
+      "calt" 1;
+    transition:
+      background-color 0.2s ease,
+      color 0.2s ease;
+  }
+
+  h1,
+  h2,
+  h3,
+  h4,
+  h5,
+  h6 {
+    font-weight: 600;
+    letter-spacing: -0.025em;
+  }
+
+  h1 {
+    font-size: 2.25rem;
+    line-height: 1.2;
+  }
+  h2 {
+    font-size: 1.875rem;
+    line-height: 1.3;
+  }
+  h3 {
+    font-size: 1.5rem;
+    line-height: 1.4;
+  }
+  h4 {
+    font-size: 1.25rem;
+  }
+  h5 {
+    font-size: 1.125rem;
+  }
+  p {
+    line-height: 1.75rem;
+  }
+
+  :focus-visible {
+    outline: none;
+    box-shadow:
+      0 0 0 2px var(--background),
+      0 0 0 4px var(--ring);
+  }
+
+  img {
+    max-width: 100%;
+    height: auto;
+  }
+
+  ::-webkit-scrollbar {
+    width: 10px;
+    height: 10px;
+  }
+
+  ::-webkit-scrollbar-track {
+    background-color: var(--secondary);
+  }
+
+  ::-webkit-scrollbar-thumb {
+    background-color: var(--muted-foreground);
+    opacity: 0.5;
+    border-radius: 0.375rem;
+  }
+
+  ::-webkit-scrollbar-thumb:hover {
+    opacity: 0.7;
+  }
+
+  ::selection {
+    background-color: var(--primary);
+    opacity: 0.2;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    *,
+    *::before,
+    *::after {
+      /* biome-ignore lint/complexity/noImportantStyles: !important is intentional for accessibility - forces reduced motion regardless of specificity */
+      animation-duration: 0.01ms !important;
+      /* biome-ignore lint/complexity/noImportantStyles: !important is intentional for accessibility - forces reduced motion regardless of specificity */
+      animation-iteration-count: 1 !important;
+      /* biome-ignore lint/complexity/noImportantStyles: !important is intentional for accessibility - forces reduced motion regardless of specificity */
+      transition-duration: 0.01ms !important;
+    }
+  }
+
+  /* Optional: set all rounded utility to use CSS var */
+  .rounded {
+    border-radius: var(--radius);
+  }
+}
+
+/* -----------------------------
+   Tailwind custom utilities
+----------------------------- */
+@layer utilities {
+  .sr-only {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border-width: 0;
+  }
+
+  .focus\:not-sr-only:focus {
+    position: static;
+    width: auto;
+    height: auto;
+    padding: initial;
+    margin: initial;
+    overflow: visible;
+    clip: auto;
+    white-space: normal;
+  }
+}

package/llms.txt

@@ -0,0 +1,193 @@
+# llms.txt — Guidance for AI systems using the Databricks AppKit (@databricks/appkit)
+
+Project: Databricks AppKit
+Author: Databricks
+Version: 1.0.0
+
+# =====================
+# General Description
+# =====================
+AppKit is a modular TypeScript SDK for building apps with workflows and plugins.
+It provides a single entrypoint (createApp) where you configure and register plugins.
+Each plugin is then available under AppKit[pluginName].
+
+Main concepts:
+- createApp(config): initializes the SDK with plugins
+- Plugins: extend AppKit with functionality (server, analytics, ai, etc.)
+- AppKit[pluginName]: exposes plugin API after initialization
+- New plugins can be created by extending the Plugin class.
+
+# =====================
+# Primary Usage Pattern
+# =====================
+Always use async/await.
+Always initialize AppKit before using plugins.
+Server and plugins already initialized, no custom endpoints.
+
+Example:
+
+```ts
+import { createApp, server, analytics } from "@databricks/appkit";
+
+await createApp({
+  plugins: [
+    server({ port: 8000 }),
+    analytics(),
+  ],
+});
+```
+
+# ==============================================
+# Basic Usage Pattern starting the server
+# ==============================================
+
+Example:
+
+```ts
+import { createApp, server, analytics } from "@databricks/appkit";
+
+const AppKit = await createApp({
+  plugins: [
+    server({ port: 8000, autoStart: false }),
+    analytics(),
+  ],
+});
+
+const app = await AppKit.server.start();
+app.get("/ping", (req, res) => res.send("pong"));
+```
+
+# =====================
+# Plugin APIs
+# =====================
+
+Each plugin exposes a set of endpoints by default.
+
+## Server Plugin
+- AppKit.server.start(): Promise<Express.Application>
+- Purpose: Start an Express server with configured port, only use if { autoStart: false } is provided in the config of the server plugin
+- Usage: Add routes via the returned app
+- Config - When setting the plugin, the following options can be provided:
+  server({
+    port?: number;
+    staticPath?: string; // This provides the path where the frontend assets are.
+    autoStart?: boolean;
+  })
+
+## Analytics Plugin
+- AppKit.analytics.query.executeQuery({ query, parameters }: { query: string; parameters?: Record<string, any> }, options?: ExecuteOptions): Promise<ExecuteStatementOutput>;
+- Purpose: Provide SQL by key interface.
+- Usage: Only for structured query + insert examples. SQL never goes into the call to the function. Any SQL that needs to be written,
+  will be written into config/queries/<query_key>.sql. All queries should be parameterized (use placeholders).
+- Default endpoints:
+  - POST /api/analytics/:query_key -> `query_key` will be the key to the file that contains the query. Expects a body with the shape { parameters?: Record<string, any>; }. parameters will be bound into the query.
+
+# =====================
+# Custom Plugins
+# =====================
+
+Databricks AppKit Might not cover all the cases needed, so for those cases a plugin can be created.
+Here is an example:
+
+```ts
+import { Plugin, toPlugin } from '@databricks/appkit';
+
+class OpenWeatherPlugin extends Plugin {
+  name: string = "open-weather";
+  private apiKey: string;
+  private url: string;
+
+  constructor(config: any, auth: IAuthManager, telemetry: ITelemetryManager) {
+    super(config, auth, telemetry);
+
+    this.apiKey = process.env.OPEN_WEATHER_API_KEY!;
+    this.url = process.env.OPEN_WEATHER_URL || "https://api.openweathermap.org/data/3.0/onecall";
+
+    // ...
+  }
+
+  async getWeather(lat: number, lon: number): Promise<any | null> {
+    const url = `${this.url}?lat=${lat}&lon=${lon}&appid=${this.apiKey}`;
+
+    try {
+      const response = await fetch(url);
+      if (!response.ok) {
+        console.error("Error fetching weather data:", response.statusText);
+        return null;
+      }
+
+      const data = await response.json();
+      return data;
+    } catch (error) {
+      console.error("Fetch error:", error);
+      return null;
+    }
+  }
+
+  /**
+   * Optionally the plugin can inject its own routes to the router
+   */
+  injectRoutes(router: express.Router) {
+    /**
+     * Each route is scoped to the plugin name. So in this case the route will be end up being
+     * /api/open-weather/weather
+     * 
+     * and an example request would be:
+     * GET /api/open-weather/weather?lat=40.7128&lon=-74.0060
+     */
+    router.get("/weather", async (req: any, res: any) => {
+      const { lat, lon } = req.query;
+      const data = await this.getWeather(lat, lon);
+      res.send(data);
+    });
+  }
+}
+
+export const openWeather = toPlugin<typeof OpenWeatherPlugin, OpenWeatherConfig, "openWeather">(OpenWeatherPlugin, "openWeather");
+```
+
+Then it would be used as the rest of the plugins
+
+```ts
+import { createApp, server, analytics } from "@databricks/appkit";
+import { openWeather } from './open-weather';
+
+const AppKit = await createApp({
+  plugins: [
+    server({ port: 8000 }),
+    analytics(),
+    openWeather(),
+  ],
+});
+
+const app = await AppKit.server.start();
+/**
+ * A route could also be added here
+ */
+app.get("/api/open-weather/weather", async (req, res) => {
+  const data = await AppKit.openWeather.getWeather(40.7128, -74.0060);
+  res.send(data);
+});
+```
+
+
+# =====================
+# Style Guidelines for AI
+# =====================
+- Always prefer async/await (never .then chaining in examples).
+- Always show explicit plugin config (no hidden defaults).
+- Use ESModules (import/export), not require().
+- Use TypeScript typings in advanced examples if helpful.
+
+# =====================
+# Anti-Patterns (avoid in examples)
+# =====================
+- ❌ Do not access AppKit internals (only use AppKit[pluginName]).
+- ❌ Do not assume SQL queries hit a real DB (they return demo data unless configured).
+- ❌ Do not show usage without createApp first.
+
+# =====================
+# Attribution
+# =====================
+If AI-generated code uses this SDK, attribute:
+"Powered by Databricks AppKit (https://github.com/...)".