@databricks/appkit-ui 0.1.4 → 0.1.5

package/dist/react/ui/menubar.d.ts

@@ -1,35 +1,35 @@
 import * as React from "react";
-import * as react_jsx_runtime171 from "react/jsx-runtime";
+import * as react_jsx_runtime163 from "react/jsx-runtime";
 import * as MenubarPrimitive from "@radix-ui/react-menubar";
 
 //#region src/react/ui/menubar.d.ts
 declare function Menubar({
   className,
   ...props
-}: React.ComponentProps<typeof MenubarPrimitive.Root>): react_jsx_runtime171.JSX.Element;
+}: React.ComponentProps<typeof MenubarPrimitive.Root>): react_jsx_runtime163.JSX.Element;
 declare function MenubarMenu({
   ...props
-}: React.ComponentProps<typeof MenubarPrimitive.Menu>): react_jsx_runtime171.JSX.Element;
+}: React.ComponentProps<typeof MenubarPrimitive.Menu>): react_jsx_runtime163.JSX.Element;
 declare function MenubarGroup({
   ...props
-}: React.ComponentProps<typeof MenubarPrimitive.Group>): react_jsx_runtime171.JSX.Element;
+}: React.ComponentProps<typeof MenubarPrimitive.Group>): react_jsx_runtime163.JSX.Element;
 declare function MenubarPortal({
   ...props
-}: React.ComponentProps<typeof MenubarPrimitive.Portal>): react_jsx_runtime171.JSX.Element;
+}: React.ComponentProps<typeof MenubarPrimitive.Portal>): react_jsx_runtime163.JSX.Element;
 declare function MenubarRadioGroup({
   ...props
-}: React.ComponentProps<typeof MenubarPrimitive.RadioGroup>): react_jsx_runtime171.JSX.Element;
+}: React.ComponentProps<typeof MenubarPrimitive.RadioGroup>): react_jsx_runtime163.JSX.Element;
 declare function MenubarTrigger({
   className,
   ...props
-}: React.ComponentProps<typeof MenubarPrimitive.Trigger>): react_jsx_runtime171.JSX.Element;
+}: React.ComponentProps<typeof MenubarPrimitive.Trigger>): react_jsx_runtime163.JSX.Element;
 declare function MenubarContent({
   className,
   align,
   alignOffset,
   sideOffset,
   ...props
-}: React.ComponentProps<typeof MenubarPrimitive.Content>): react_jsx_runtime171.JSX.Element;
+}: React.ComponentProps<typeof MenubarPrimitive.Content>): react_jsx_runtime163.JSX.Element;
 declare function MenubarItem({
   className,
   inset,
@@ -38,36 +38,36 @@ declare function MenubarItem({
 }: React.ComponentProps<typeof MenubarPrimitive.Item> & {
   inset?: boolean;
   variant?: "default" | "destructive";
-}): react_jsx_runtime171.JSX.Element;
+}): react_jsx_runtime163.JSX.Element;
 declare function MenubarCheckboxItem({
   className,
   children,
   checked,
   ...props
-}: React.ComponentProps<typeof MenubarPrimitive.CheckboxItem>): react_jsx_runtime171.JSX.Element;
+}: React.ComponentProps<typeof MenubarPrimitive.CheckboxItem>): react_jsx_runtime163.JSX.Element;
 declare function MenubarRadioItem({
   className,
   children,
   ...props
-}: React.ComponentProps<typeof MenubarPrimitive.RadioItem>): react_jsx_runtime171.JSX.Element;
+}: React.ComponentProps<typeof MenubarPrimitive.RadioItem>): react_jsx_runtime163.JSX.Element;
 declare function MenubarLabel({
   className,
   inset,
   ...props
 }: React.ComponentProps<typeof MenubarPrimitive.Label> & {
   inset?: boolean;
-}): react_jsx_runtime171.JSX.Element;
+}): react_jsx_runtime163.JSX.Element;
 declare function MenubarSeparator({
   className,
   ...props
-}: React.ComponentProps<typeof MenubarPrimitive.Separator>): react_jsx_runtime171.JSX.Element;
+}: React.ComponentProps<typeof MenubarPrimitive.Separator>): react_jsx_runtime163.JSX.Element;
 declare function MenubarShortcut({
   className,
   ...props
-}: React.ComponentProps<"span">): react_jsx_runtime171.JSX.Element;
+}: React.ComponentProps<"span">): react_jsx_runtime163.JSX.Element;
 declare function MenubarSub({
   ...props
-}: React.ComponentProps<typeof MenubarPrimitive.Sub>): react_jsx_runtime171.JSX.Element;
+}: React.ComponentProps<typeof MenubarPrimitive.Sub>): react_jsx_runtime163.JSX.Element;
 declare function MenubarSubTrigger({
   className,
   inset,
@@ -75,11 +75,11 @@ declare function MenubarSubTrigger({
   ...props
 }: React.ComponentProps<typeof MenubarPrimitive.SubTrigger> & {
   inset?: boolean;
-}): react_jsx_runtime171.JSX.Element;
+}): react_jsx_runtime163.JSX.Element;
 declare function MenubarSubContent({
   className,
   ...props
-}: React.ComponentProps<typeof MenubarPrimitive.SubContent>): react_jsx_runtime171.JSX.Element;
+}: React.ComponentProps<typeof MenubarPrimitive.SubContent>): react_jsx_runtime163.JSX.Element;
 //#endregion
 export { Menubar, MenubarCheckboxItem, MenubarContent, MenubarGroup, MenubarItem, MenubarLabel, MenubarMenu, MenubarPortal, MenubarRadioGroup, MenubarRadioItem, MenubarSeparator, MenubarShortcut, MenubarSub, MenubarSubContent, MenubarSubTrigger, MenubarTrigger };
 //# sourceMappingURL=menubar.d.ts.map

package/dist/react/ui/navigation-menu.d.ts

@@ -1,5 +1,5 @@
 import * as React from "react";
-import * as react_jsx_runtime163 from "react/jsx-runtime";
+import * as react_jsx_runtime179 from "react/jsx-runtime";
 import * as NavigationMenuPrimitive from "@radix-ui/react-navigation-menu";
 import * as class_variance_authority_types9 from "class-variance-authority/types";
 
@@ -11,37 +11,37 @@ declare function NavigationMenu({
   ...props
 }: React.ComponentProps<typeof NavigationMenuPrimitive.Root> & {
   viewport?: boolean;
-}): react_jsx_runtime163.JSX.Element;
+}): react_jsx_runtime179.JSX.Element;
 declare function NavigationMenuList({
   className,
   ...props
-}: React.ComponentProps<typeof NavigationMenuPrimitive.List>): react_jsx_runtime163.JSX.Element;
+}: React.ComponentProps<typeof NavigationMenuPrimitive.List>): react_jsx_runtime179.JSX.Element;
 declare function NavigationMenuItem({
   className,
   ...props
-}: React.ComponentProps<typeof NavigationMenuPrimitive.Item>): react_jsx_runtime163.JSX.Element;
+}: React.ComponentProps<typeof NavigationMenuPrimitive.Item>): react_jsx_runtime179.JSX.Element;
 declare const navigationMenuTriggerStyle: (props?: class_variance_authority_types9.ClassProp | undefined) => string;
 declare function NavigationMenuTrigger({
   className,
   children,
   ...props
-}: React.ComponentProps<typeof NavigationMenuPrimitive.Trigger>): react_jsx_runtime163.JSX.Element;
+}: React.ComponentProps<typeof NavigationMenuPrimitive.Trigger>): react_jsx_runtime179.JSX.Element;
 declare function NavigationMenuContent({
   className,
   ...props
-}: React.ComponentProps<typeof NavigationMenuPrimitive.Content>): react_jsx_runtime163.JSX.Element;
+}: React.ComponentProps<typeof NavigationMenuPrimitive.Content>): react_jsx_runtime179.JSX.Element;
 declare function NavigationMenuViewport({
   className,
   ...props
-}: React.ComponentProps<typeof NavigationMenuPrimitive.Viewport>): react_jsx_runtime163.JSX.Element;
+}: React.ComponentProps<typeof NavigationMenuPrimitive.Viewport>): react_jsx_runtime179.JSX.Element;
 declare function NavigationMenuLink({
   className,
   ...props
-}: React.ComponentProps<typeof NavigationMenuPrimitive.Link>): react_jsx_runtime163.JSX.Element;
+}: React.ComponentProps<typeof NavigationMenuPrimitive.Link>): react_jsx_runtime179.JSX.Element;
 declare function NavigationMenuIndicator({
   className,
   ...props
-}: React.ComponentProps<typeof NavigationMenuPrimitive.Indicator>): react_jsx_runtime163.JSX.Element;
+}: React.ComponentProps<typeof NavigationMenuPrimitive.Indicator>): react_jsx_runtime179.JSX.Element;
 //#endregion
 export { NavigationMenu, NavigationMenuContent, NavigationMenuIndicator, NavigationMenuItem, NavigationMenuLink, NavigationMenuList, NavigationMenuTrigger, NavigationMenuViewport, navigationMenuTriggerStyle };
 //# sourceMappingURL=navigation-menu.d.ts.map

package/dist/shared/src/sql/helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"helpers.js","names":["dateValue: string","timestampValue: string","numValue: string","stringValue: string","booleanValue: string","hexValue: string"],"sources":["../../../../../shared/src/sql/helpers.ts"],"sourcesContent":["import type {\n  SQLBinaryMarker,\n  SQLBooleanMarker,\n  SQLDateMarker,\n  SQLNumberMarker,\n  SQLStringMarker,\n  SQLTimestampMarker,\n  SQLTypeMarker,\n} from \"./types\";\n\n/**\n * SQL helper namespace\n */\nexport const sql = {\n  /**\n   * Creates a DATE type parameter\n   * Accepts Date objects or ISO date strings (YYYY-MM-DD format)\n   * @param value - Date object or ISO date string\n   * @returns Marker object for DATE type parameter\n   * @example\n   * ```typescript\n   * const params = { startDate: sql.date(new Date(\"2024-01-01\")) };\n   * params = { startDate: \"2024-01-01\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { startDate: sql.date(\"2024-01-01\") };\n   * params = { startDate: \"2024-01-01\" }\n   * ```\n   */\n  date(value: Date | string): SQLDateMarker {\n    let dateValue: string = \"\";\n\n    // check if value is a Date object\n    if (value instanceof Date) {\n      dateValue = value.toISOString().split(\"T\")[0];\n    }\n    // check if value is a string\n    else if (typeof value === \"string\") {\n      // validate format\n      if (!/^\\d{4}-\\d{2}-\\d{2}$/.test(value)) {\n        throw new Error(\n          `sql.date() expects Date or ISO date string (YYYY-MM-DD format), got: ${value}`,\n        );\n      }\n      dateValue = value;\n    }\n    // if value is not a Date object or string, throw an error\n    else {\n      throw new Error(\n        `sql.date() expects Date or ISO date string (YYYY-MM-DD format), got: ${typeof value}`,\n      );\n    }\n\n    return {\n      __sql_type: \"DATE\",\n      value: dateValue,\n    };\n  },\n\n  /**\n   * Creates a TIMESTAMP type parameter\n   * Accepts Date objects, ISO timestamp strings, or Unix timestamp numbers\n   * @param value - Date object, ISO timestamp string, or Unix timestamp number\n   * @returns Marker object for TIMESTAMP type parameter\n   * @example\n   * ```typescript\n   * const params = { createdTime: sql.timestamp(new Date(\"2024-01-01T12:00:00Z\")) };\n   * params = { createdTime: \"2024-01-01T12:00:00Z\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { createdTime: sql.timestamp(\"2024-01-01T12:00:00Z\") };\n   * params = { createdTime: \"2024-01-01T12:00:00Z\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { createdTime: sql.timestamp(1704110400000) };\n   * params = { createdTime: \"2024-01-01T12:00:00Z\" }\n   * ```\n   */\n  timestamp(value: Date | string | number): SQLTimestampMarker {\n    let timestampValue: string = \"\";\n\n    if (value instanceof Date) {\n      timestampValue = value.toISOString().replace(/\\.000(Z|[+-])/, \"$1\");\n    } else if (typeof value === \"string\") {\n      const isoRegex =\n        /^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?(Z|[+-]\\d{2}:\\d{2})?$/;\n      if (!isoRegex.test(value)) {\n        throw new Error(\n          `sql.timestamp() expects ISO timestamp string (YYYY-MM-DDTHH:MM:SS.mmmZ or YYYY-MM-DDTHH:MM:SS.mmm+HH:MM), got: ${value}`,\n        );\n      }\n      timestampValue = value;\n    } else if (typeof value === \"number\") {\n      const date = new Date(value > 1e12 ? value : value * 1000);\n      timestampValue = date.toISOString().replace(/\\.000(Z|[+-])/, \"$1\");\n    } else {\n      throw new Error(\n        `sql.timestamp() expects Date, ISO timestamp string, or Unix timestamp number, got: ${typeof value}`,\n      );\n    }\n\n    return {\n      __sql_type: \"TIMESTAMP\",\n      value: timestampValue,\n    };\n  },\n\n  /**\n   * Creates a NUMERIC type parameter\n   * Accepts numbers or numeric strings\n   * @param value - Number or numeric string\n   * @returns Marker object for NUMERIC type parameter\n   * @example\n   * ```typescript\n   * const params = { userId: sql.number(123) };\n   * params = { userId: \"123\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { userId: sql.number(\"123\") };\n   * params = { userId: \"123\" }\n   * ```\n   */\n  number(value: number | string): SQLNumberMarker {\n    let numValue: string = \"\";\n\n    // check if value is a number\n    if (typeof value === \"number\") {\n      numValue = value.toString();\n    }\n    // check if value is a string\n    else if (typeof value === \"string\") {\n      if (value === \"\" || Number.isNaN(Number(value))) {\n        throw new Error(\n          `sql.number() expects number or numeric string, got: ${value === \"\" ? \"empty string\" : value}`,\n        );\n      }\n      numValue = value;\n    }\n    // if value is not a number or string, throw an error\n    else {\n      throw new Error(\n        `sql.number() expects number or numeric string, got: ${typeof value}`,\n      );\n    }\n\n    return {\n      __sql_type: \"NUMERIC\",\n      value: numValue,\n    };\n  },\n\n  /**\n   * Creates a STRING type parameter\n   * Accepts strings, numbers, or booleans\n   * @param value - String, number, or boolean\n   * @returns Marker object for STRING type parameter\n   * @example\n   * ```typescript\n   * const params = { name: sql.string(\"John\") };\n   * params = { name: \"John\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { name: sql.string(123) };\n   * params = { name: \"123\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { name: sql.string(true) };\n   * params = { name: \"true\" }\n   * ```\n   */\n  string(value: string | number | boolean): SQLStringMarker {\n    if (\n      typeof value !== \"string\" &&\n      typeof value !== \"number\" &&\n      typeof value !== \"boolean\"\n    ) {\n      throw new Error(\n        `sql.string() expects string or number or boolean, got: ${typeof value}`,\n      );\n    }\n\n    let stringValue: string = \"\";\n\n    if (typeof value === \"string\") {\n      stringValue = value;\n    } else {\n      stringValue = value.toString();\n    }\n\n    return {\n      __sql_type: \"STRING\",\n      value: stringValue,\n    };\n  },\n\n  /**\n   * Create a BOOLEAN type parameter\n   * Accepts booleans, strings, or numbers\n   * @param value - Boolean, string, or number\n   * @returns Marker object for BOOLEAN type parameter\n   * @example\n   * ```typescript\n   * const params = { isActive: sql.boolean(true) };\n   * params = { isActive: \"true\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { isActive: sql.boolean(\"true\") };\n   * params = { isActive: \"true\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { isActive: sql.boolean(1) };\n   * params = { isActive: \"true\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { isActive: sql.boolean(\"false\") };\n   * params = { isActive: \"false\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { isActive: sql.boolean(0) };\n   * params = { isActive: \"false\" }\n   * ```\n   * @returns\n   */\n  boolean(value: boolean | string | number): SQLBooleanMarker {\n    if (\n      typeof value !== \"boolean\" &&\n      typeof value !== \"string\" &&\n      typeof value !== \"number\"\n    ) {\n      throw new Error(\n        `sql.boolean() expects boolean or string (true or false) or number (1 or 0), got: ${typeof value}`,\n      );\n    }\n\n    let booleanValue: string = \"\";\n\n    if (typeof value === \"boolean\") {\n      booleanValue = value.toString();\n    }\n    // check if value is a number\n    else if (typeof value === \"number\") {\n      if (value !== 1 && value !== 0) {\n        throw new Error(\n          `sql.boolean() expects boolean or string (true or false) or number (1 or 0), got: ${value}`,\n        );\n      }\n      booleanValue = value === 1 ? \"true\" : \"false\";\n    }\n    // check if value is a string\n    else if (typeof value === \"string\") {\n      if (value !== \"true\" && value !== \"false\") {\n        throw new Error(\n          `sql.boolean() expects boolean or string (true or false) or number (1 or 0), got: ${value}`,\n        );\n      }\n      booleanValue = value;\n    }\n\n    return {\n      __sql_type: \"BOOLEAN\",\n      value: booleanValue,\n    };\n  },\n\n  /**\n   * Creates a BINARY parameter as hex-encoded STRING\n   * Accepts Uint8Array, ArrayBuffer, or hex string\n   * Note: Databricks SQL Warehouse doesn't support BINARY as parameter type,\n   * so this helper returns a STRING with hex encoding. Use UNHEX(:param) in your SQL.\n   * @param value - Uint8Array, ArrayBuffer, or hex string\n   * @returns Marker object with STRING type and hex-encoded value\n   * @example\n   * ```typescript\n   * // From Uint8Array:\n   * const params = { data: sql.binary(new Uint8Array([0x53, 0x70, 0x61, 0x72, 0x6b])) };\n   * // Returns: { __sql_type: \"STRING\", value: \"537061726B\" }\n   * // SQL: SELECT UNHEX(:data) as binary_value\n   * ```\n   * @example\n   * ```typescript\n   * // From hex string:\n   * const params = { data: sql.binary(\"537061726B\") };\n   * // Returns: { __sql_type: \"STRING\", value: \"537061726B\" }\n   * ```\n   */\n  binary(value: Uint8Array | ArrayBuffer | string): SQLBinaryMarker {\n    let hexValue: string = \"\";\n\n    if (value instanceof Uint8Array) {\n      // if value is a Uint8Array, convert it to a hex string\n      hexValue = Array.from(value)\n        .map((b) => b.toString(16).padStart(2, \"0\").toUpperCase())\n        .join(\"\");\n    } else if (value instanceof ArrayBuffer) {\n      // if value is an ArrayBuffer, convert it to a hex string\n      hexValue = Array.from(new Uint8Array(value))\n        .map((b) => b.toString(16).padStart(2, \"0\").toUpperCase())\n        .join(\"\");\n    } else if (typeof value === \"string\") {\n      // validate hex string\n      if (!/^[0-9A-Fa-f]*$/.test(value)) {\n        throw new Error(\n          `sql.binary() expects Uint8Array, ArrayBuffer, or hex string, got invalid hex: ${value}`,\n        );\n      }\n      hexValue = value.toUpperCase();\n    } else {\n      throw new Error(\n        `sql.binary() expects Uint8Array, ArrayBuffer, or hex string, got: ${typeof value}`,\n      );\n    }\n\n    return {\n      __sql_type: \"STRING\",\n      value: hexValue,\n    };\n  },\n};\n\n/**\n * Type guard to check if a value is a SQL type marker\n * @param value - Value to check\n * @returns True if the value is a SQL type marker, false otherwise\n * @example\n * ```typescript\n * const value = {\n *   __sql_type: \"DATE\",\n *   value: \"2024-01-01\",\n * };\n * const isSQLTypeMarker = isSQLTypeMarker(value);\n * console.log(isSQLTypeMarker); // true\n * ```\n */\nexport function isSQLTypeMarker(value: any): value is SQLTypeMarker {\n  return (\n    value !== null &&\n    typeof value === \"object\" &&\n    \"__sql_type\" in value &&\n    \"value\" in value &&\n    typeof value.__sql_type === \"string\" &&\n    typeof value.value === \"string\"\n  );\n}\n"],"mappings":"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"}
+{"version":3,"file":"helpers.js","names":[],"sources":["../../../../../shared/src/sql/helpers.ts"],"sourcesContent":["import type {\n  SQLBinaryMarker,\n  SQLBooleanMarker,\n  SQLDateMarker,\n  SQLNumberMarker,\n  SQLStringMarker,\n  SQLTimestampMarker,\n  SQLTypeMarker,\n} from \"./types\";\n\n/**\n * SQL helper namespace\n */\nexport const sql = {\n  /**\n   * Creates a DATE type parameter\n   * Accepts Date objects or ISO date strings (YYYY-MM-DD format)\n   * @param value - Date object or ISO date string\n   * @returns Marker object for DATE type parameter\n   * @example\n   * ```typescript\n   * const params = { startDate: sql.date(new Date(\"2024-01-01\")) };\n   * params = { startDate: \"2024-01-01\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { startDate: sql.date(\"2024-01-01\") };\n   * params = { startDate: \"2024-01-01\" }\n   * ```\n   */\n  date(value: Date | string): SQLDateMarker {\n    let dateValue: string = \"\";\n\n    // check if value is a Date object\n    if (value instanceof Date) {\n      dateValue = value.toISOString().split(\"T\")[0];\n    }\n    // check if value is a string\n    else if (typeof value === \"string\") {\n      // validate format\n      if (!/^\\d{4}-\\d{2}-\\d{2}$/.test(value)) {\n        throw new Error(\n          `sql.date() expects Date or ISO date string (YYYY-MM-DD format), got: ${value}`,\n        );\n      }\n      dateValue = value;\n    }\n    // if value is not a Date object or string, throw an error\n    else {\n      throw new Error(\n        `sql.date() expects Date or ISO date string (YYYY-MM-DD format), got: ${typeof value}`,\n      );\n    }\n\n    return {\n      __sql_type: \"DATE\",\n      value: dateValue,\n    };\n  },\n\n  /**\n   * Creates a TIMESTAMP type parameter\n   * Accepts Date objects, ISO timestamp strings, or Unix timestamp numbers\n   * @param value - Date object, ISO timestamp string, or Unix timestamp number\n   * @returns Marker object for TIMESTAMP type parameter\n   * @example\n   * ```typescript\n   * const params = { createdTime: sql.timestamp(new Date(\"2024-01-01T12:00:00Z\")) };\n   * params = { createdTime: \"2024-01-01T12:00:00Z\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { createdTime: sql.timestamp(\"2024-01-01T12:00:00Z\") };\n   * params = { createdTime: \"2024-01-01T12:00:00Z\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { createdTime: sql.timestamp(1704110400000) };\n   * params = { createdTime: \"2024-01-01T12:00:00Z\" }\n   * ```\n   */\n  timestamp(value: Date | string | number): SQLTimestampMarker {\n    let timestampValue: string = \"\";\n\n    if (value instanceof Date) {\n      timestampValue = value.toISOString().replace(/\\.000(Z|[+-])/, \"$1\");\n    } else if (typeof value === \"string\") {\n      const isoRegex =\n        /^\\d{4}-\\d{2}-\\d{2}T\\d{2}:\\d{2}:\\d{2}(\\.\\d{1,9})?(Z|[+-]\\d{2}:\\d{2})?$/;\n      if (!isoRegex.test(value)) {\n        throw new Error(\n          `sql.timestamp() expects ISO timestamp string (YYYY-MM-DDTHH:MM:SS.mmmZ or YYYY-MM-DDTHH:MM:SS.mmm+HH:MM), got: ${value}`,\n        );\n      }\n      timestampValue = value;\n    } else if (typeof value === \"number\") {\n      const date = new Date(value > 1e12 ? value : value * 1000);\n      timestampValue = date.toISOString().replace(/\\.000(Z|[+-])/, \"$1\");\n    } else {\n      throw new Error(\n        `sql.timestamp() expects Date, ISO timestamp string, or Unix timestamp number, got: ${typeof value}`,\n      );\n    }\n\n    return {\n      __sql_type: \"TIMESTAMP\",\n      value: timestampValue,\n    };\n  },\n\n  /**\n   * Creates a NUMERIC type parameter\n   * Accepts numbers or numeric strings\n   * @param value - Number or numeric string\n   * @returns Marker object for NUMERIC type parameter\n   * @example\n   * ```typescript\n   * const params = { userId: sql.number(123) };\n   * params = { userId: \"123\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { userId: sql.number(\"123\") };\n   * params = { userId: \"123\" }\n   * ```\n   */\n  number(value: number | string): SQLNumberMarker {\n    let numValue: string = \"\";\n\n    // check if value is a number\n    if (typeof value === \"number\") {\n      numValue = value.toString();\n    }\n    // check if value is a string\n    else if (typeof value === \"string\") {\n      if (value === \"\" || Number.isNaN(Number(value))) {\n        throw new Error(\n          `sql.number() expects number or numeric string, got: ${value === \"\" ? \"empty string\" : value}`,\n        );\n      }\n      numValue = value;\n    }\n    // if value is not a number or string, throw an error\n    else {\n      throw new Error(\n        `sql.number() expects number or numeric string, got: ${typeof value}`,\n      );\n    }\n\n    return {\n      __sql_type: \"NUMERIC\",\n      value: numValue,\n    };\n  },\n\n  /**\n   * Creates a STRING type parameter\n   * Accepts strings, numbers, or booleans\n   * @param value - String, number, or boolean\n   * @returns Marker object for STRING type parameter\n   * @example\n   * ```typescript\n   * const params = { name: sql.string(\"John\") };\n   * params = { name: \"John\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { name: sql.string(123) };\n   * params = { name: \"123\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { name: sql.string(true) };\n   * params = { name: \"true\" }\n   * ```\n   */\n  string(value: string | number | boolean): SQLStringMarker {\n    if (\n      typeof value !== \"string\" &&\n      typeof value !== \"number\" &&\n      typeof value !== \"boolean\"\n    ) {\n      throw new Error(\n        `sql.string() expects string or number or boolean, got: ${typeof value}`,\n      );\n    }\n\n    let stringValue: string = \"\";\n\n    if (typeof value === \"string\") {\n      stringValue = value;\n    } else {\n      stringValue = value.toString();\n    }\n\n    return {\n      __sql_type: \"STRING\",\n      value: stringValue,\n    };\n  },\n\n  /**\n   * Create a BOOLEAN type parameter\n   * Accepts booleans, strings, or numbers\n   * @param value - Boolean, string, or number\n   * @returns Marker object for BOOLEAN type parameter\n   * @example\n   * ```typescript\n   * const params = { isActive: sql.boolean(true) };\n   * params = { isActive: \"true\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { isActive: sql.boolean(\"true\") };\n   * params = { isActive: \"true\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { isActive: sql.boolean(1) };\n   * params = { isActive: \"true\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { isActive: sql.boolean(\"false\") };\n   * params = { isActive: \"false\" }\n   * ```\n   * @example\n   * ```typescript\n   * const params = { isActive: sql.boolean(0) };\n   * params = { isActive: \"false\" }\n   * ```\n   * @returns\n   */\n  boolean(value: boolean | string | number): SQLBooleanMarker {\n    if (\n      typeof value !== \"boolean\" &&\n      typeof value !== \"string\" &&\n      typeof value !== \"number\"\n    ) {\n      throw new Error(\n        `sql.boolean() expects boolean or string (true or false) or number (1 or 0), got: ${typeof value}`,\n      );\n    }\n\n    let booleanValue: string = \"\";\n\n    if (typeof value === \"boolean\") {\n      booleanValue = value.toString();\n    }\n    // check if value is a number\n    else if (typeof value === \"number\") {\n      if (value !== 1 && value !== 0) {\n        throw new Error(\n          `sql.boolean() expects boolean or string (true or false) or number (1 or 0), got: ${value}`,\n        );\n      }\n      booleanValue = value === 1 ? \"true\" : \"false\";\n    }\n    // check if value is a string\n    else if (typeof value === \"string\") {\n      if (value !== \"true\" && value !== \"false\") {\n        throw new Error(\n          `sql.boolean() expects boolean or string (true or false) or number (1 or 0), got: ${value}`,\n        );\n      }\n      booleanValue = value;\n    }\n\n    return {\n      __sql_type: \"BOOLEAN\",\n      value: booleanValue,\n    };\n  },\n\n  /**\n   * Creates a BINARY parameter as hex-encoded STRING\n   * Accepts Uint8Array, ArrayBuffer, or hex string\n   * Note: Databricks SQL Warehouse doesn't support BINARY as parameter type,\n   * so this helper returns a STRING with hex encoding. Use UNHEX(:param) in your SQL.\n   * @param value - Uint8Array, ArrayBuffer, or hex string\n   * @returns Marker object with STRING type and hex-encoded value\n   * @example\n   * ```typescript\n   * // From Uint8Array:\n   * const params = { data: sql.binary(new Uint8Array([0x53, 0x70, 0x61, 0x72, 0x6b])) };\n   * // Returns: { __sql_type: \"STRING\", value: \"537061726B\" }\n   * // SQL: SELECT UNHEX(:data) as binary_value\n   * ```\n   * @example\n   * ```typescript\n   * // From hex string:\n   * const params = { data: sql.binary(\"537061726B\") };\n   * // Returns: { __sql_type: \"STRING\", value: \"537061726B\" }\n   * ```\n   */\n  binary(value: Uint8Array | ArrayBuffer | string): SQLBinaryMarker {\n    let hexValue: string = \"\";\n\n    if (value instanceof Uint8Array) {\n      // if value is a Uint8Array, convert it to a hex string\n      hexValue = Array.from(value)\n        .map((b) => b.toString(16).padStart(2, \"0\").toUpperCase())\n        .join(\"\");\n    } else if (value instanceof ArrayBuffer) {\n      // if value is an ArrayBuffer, convert it to a hex string\n      hexValue = Array.from(new Uint8Array(value))\n        .map((b) => b.toString(16).padStart(2, \"0\").toUpperCase())\n        .join(\"\");\n    } else if (typeof value === \"string\") {\n      // validate hex string\n      if (!/^[0-9A-Fa-f]*$/.test(value)) {\n        throw new Error(\n          `sql.binary() expects Uint8Array, ArrayBuffer, or hex string, got invalid hex: ${value}`,\n        );\n      }\n      hexValue = value.toUpperCase();\n    } else {\n      throw new Error(\n        `sql.binary() expects Uint8Array, ArrayBuffer, or hex string, got: ${typeof value}`,\n      );\n    }\n\n    return {\n      __sql_type: \"STRING\",\n      value: hexValue,\n    };\n  },\n};\n\n/**\n * Type guard to check if a value is a SQL type marker\n * @param value - Value to check\n * @returns True if the value is a SQL type marker, false otherwise\n * @example\n * ```typescript\n * const value = {\n *   __sql_type: \"DATE\",\n *   value: \"2024-01-01\",\n * };\n * const isSQLTypeMarker = isSQLTypeMarker(value);\n * console.log(isSQLTypeMarker); // true\n * ```\n */\nexport function isSQLTypeMarker(value: any): value is SQLTypeMarker {\n  return (\n    value !== null &&\n    typeof value === \"object\" &&\n    \"__sql_type\" in value &&\n    \"value\" in value &&\n    typeof value.__sql_type === \"string\" &&\n    typeof value.value === \"string\"\n  );\n}\n"],"mappings":";;;;AAaA,MAAa,MAAM;CAiBjB,KAAK,OAAqC;EACxC,IAAI,YAAoB;AAGxB,MAAI,iBAAiB,KACnB,aAAY,MAAM,aAAa,CAAC,MAAM,IAAI,CAAC;WAGpC,OAAO,UAAU,UAAU;AAElC,OAAI,CAAC,sBAAsB,KAAK,MAAM,CACpC,OAAM,IAAI,MACR,wEAAwE,QACzE;AAEH,eAAY;QAIZ,OAAM,IAAI,MACR,wEAAwE,OAAO,QAChF;AAGH,SAAO;GACL,YAAY;GACZ,OAAO;GACR;;CAwBH,UAAU,OAAmD;EAC3D,IAAI,iBAAyB;AAE7B,MAAI,iBAAiB,KACnB,kBAAiB,MAAM,aAAa,CAAC,QAAQ,iBAAiB,KAAK;WAC1D,OAAO,UAAU,UAAU;AAGpC,OAAI,CADF,wEACY,KAAK,MAAM,CACvB,OAAM,IAAI,MACR,kHAAkH,QACnH;AAEH,oBAAiB;aACR,OAAO,UAAU,SAE1B,kBADa,IAAI,KAAK,QAAQ,eAAO,QAAQ,QAAQ,IAAK,CACpC,aAAa,CAAC,QAAQ,iBAAiB,KAAK;MAElE,OAAM,IAAI,MACR,sFAAsF,OAAO,QAC9F;AAGH,SAAO;GACL,YAAY;GACZ,OAAO;GACR;;CAmBH,OAAO,OAAyC;EAC9C,IAAI,WAAmB;AAGvB,MAAI,OAAO,UAAU,SACnB,YAAW,MAAM,UAAU;WAGpB,OAAO,UAAU,UAAU;AAClC,OAAI,UAAU,MAAM,OAAO,MAAM,OAAO,MAAM,CAAC,CAC7C,OAAM,IAAI,MACR,uDAAuD,UAAU,KAAK,iBAAiB,QACxF;AAEH,cAAW;QAIX,OAAM,IAAI,MACR,uDAAuD,OAAO,QAC/D;AAGH,SAAO;GACL,YAAY;GACZ,OAAO;GACR;;CAwBH,OAAO,OAAmD;AACxD,MACE,OAAO,UAAU,YACjB,OAAO,UAAU,YACjB,OAAO,UAAU,UAEjB,OAAM,IAAI,MACR,0DAA0D,OAAO,QAClE;EAGH,IAAI,cAAsB;AAE1B,MAAI,OAAO,UAAU,SACnB,eAAc;MAEd,eAAc,MAAM,UAAU;AAGhC,SAAO;GACL,YAAY;GACZ,OAAO;GACR;;CAmCH,QAAQ,OAAoD;AAC1D,MACE,OAAO,UAAU,aACjB,OAAO,UAAU,YACjB,OAAO,UAAU,SAEjB,OAAM,IAAI,MACR,oFAAoF,OAAO,QAC5F;EAGH,IAAI,eAAuB;AAE3B,MAAI,OAAO,UAAU,UACnB,gBAAe,MAAM,UAAU;WAGxB,OAAO,UAAU,UAAU;AAClC,OAAI,UAAU,KAAK,UAAU,EAC3B,OAAM,IAAI,MACR,oFAAoF,QACrF;AAEH,kBAAe,UAAU,IAAI,SAAS;aAG/B,OAAO,UAAU,UAAU;AAClC,OAAI,UAAU,UAAU,UAAU,QAChC,OAAM,IAAI,MACR,oFAAoF,QACrF;AAEH,kBAAe;;AAGjB,SAAO;GACL,YAAY;GACZ,OAAO;GACR;;CAwBH,OAAO,OAA2D;EAChE,IAAI,WAAmB;AAEvB,MAAI,iBAAiB,WAEnB,YAAW,MAAM,KAAK,MAAM,CACzB,KAAK,MAAM,EAAE,SAAS,GAAG,CAAC,SAAS,GAAG,IAAI,CAAC,aAAa,CAAC,CACzD,KAAK,GAAG;WACF,iBAAiB,YAE1B,YAAW,MAAM,KAAK,IAAI,WAAW,MAAM,CAAC,CACzC,KAAK,MAAM,EAAE,SAAS,GAAG,CAAC,SAAS,GAAG,IAAI,CAAC,aAAa,CAAC,CACzD,KAAK,GAAG;WACF,OAAO,UAAU,UAAU;AAEpC,OAAI,CAAC,iBAAiB,KAAK,MAAM,CAC/B,OAAM,IAAI,MACR,iFAAiF,QAClF;AAEH,cAAW,MAAM,aAAa;QAE9B,OAAM,IAAI,MACR,qEAAqE,OAAO,QAC7E;AAGH,SAAO;GACL,YAAY;GACZ,OAAO;GACR;;CAEJ;;;;;;;;;;;;;;;AAgBD,SAAgB,gBAAgB,OAAoC;AAClE,QACE,UAAU,QACV,OAAO,UAAU,YACjB,gBAAgB,SAChB,WAAW,SACX,OAAO,MAAM,eAAe,YAC5B,OAAO,MAAM,UAAU"}

package/llms.txt

@@ -440,23 +440,49 @@ Formats:
 - `format: "JSON"` (default) returns JSON rows
 - `format: "ARROW"` returns an Arrow “statement_id” payload over SSE, then the client fetches binary Arrow from `/api/analytics/arrow-result/:jobId`
 
-### Request context (`getRequestContext()`)
+### Execution context and `asUser(req)`
 
-If a plugin sets `requiresDatabricksClient = true`, AppKit adds middleware that provides request context.
+AppKit manages Databricks authentication via two contexts:
 
-Headers used:
+- **ServiceContext** (singleton): Initialized at app startup with service principal credentials
+- **ExecutionContext**: Determined at runtime - either service principal or user context
+
+**Headers used for user context:**
 
 - `x-forwarded-user`: required in production; identifies the user
-- `x-forwarded-access-token`: optional; enables **user token passthrough** if `DATABRICKS_HOST` is set
+- `x-forwarded-access-token`: required for user token passthrough
+
+**Using `asUser(req)` for user-scoped operations:**
+
+The `asUser(req)` pattern allows plugins to execute operations using the requesting user's credentials:
+
+```ts
+// In a custom plugin route handler
+router.post("/users/me/data", async (req, res) => {
+  // Execute as the user (uses their Databricks permissions)
+  const result = await this.asUser(req).query("SELECT ...");
+  res.json(result);
+});
+
+// Service principal execution (default)
+router.post("/system/data", async (req, res) => {
+  const result = await this.query("SELECT ...");
+  res.json(result);
+});
+```
+
+**Context helper functions (exported from `@databricks/appkit`):**
+
+- `getExecutionContext()`: Returns current context (user or service)
+- `getCurrentUserId()`: Returns user ID in user context, service user ID otherwise
+- `getWorkspaceClient()`: Returns the appropriate WorkspaceClient for current context
+- `getWarehouseId()`: `Promise<string>` (from `DATABRICKS_WAREHOUSE_ID` or auto-selected in dev)
+- `getWorkspaceId()`: `Promise<string>` (from `DATABRICKS_WORKSPACE_ID` or fetched)
+- `isInUserContext()`: Returns `true` if currently executing in user context
 
-Context fields (real behavior):
+**Development mode behavior:**
 
-- `userId`: derived from `x-forwarded-user` (in development it falls back to `serviceUserId`)
-- `serviceUserId`: service principal/user ID
-- `warehouseId`: `Promise<string>` (from `DATABRICKS_WAREHOUSE_ID`, or auto-selected in development)
-- `workspaceId`: `Promise<string>` (from `DATABRICKS_WORKSPACE_ID` or fetched)
-- `userDatabricksClient`: present only when passthrough is available (or in dev it equals service client)
-- `serviceDatabricksClient`: always present
+In local development (`NODE_ENV=development`), if `asUser(req)` is called without a user token, it logs a warning and falls back to the service principal.
 
 ### Custom plugins (backend)
 
@@ -469,7 +495,6 @@ import type express from "express";
 class MyPlugin extends Plugin {
   name = "my-plugin";
   envVars = [];                 // list required env vars here
-  requiresDatabricksClient = false; // set true if you need getRequestContext()
 
   injectRoutes(router: express.Router) {
     this.route(router, {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@databricks/appkit-ui",
   "type": "module",
-  "version": "0.1.4",
+  "version": "0.1.5",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/databricks/appkit.git"