react-semaphor 0.1.325 → 0.1.327

package/dist/types/dashboard.d.ts

@@ -812,6 +812,7 @@ declare interface DataModelEntityReference extends DatabaseEntityReference {
 declare interface DatasetEntityReference extends DatabaseEntityReference {
     type: 'dataset';
     datasetType: 'physical' | 'virtual';
+    table?: string | null;
     datamodelId?: string | null;
     sql?: string | null;
     id: string;
@@ -1468,6 +1469,16 @@ declare type FormatSpec = {
     sourceTimezone?: string;
     prefix?: string;
     suffix?: string;
+} | {
+    type: 'duration';
+    inputUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    outputStyle?: 'compact' | 'digital' | 'long';
+    largestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    smallestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    maxUnits?: number;
+    prefix?: string;
+    suffix?: string;
+    negativeStyle?: 'minus' | 'parentheses';
 } | {
     type: 'string';
     prefix?: string;
@@ -2500,7 +2511,11 @@ export declare type TDataColumn = {
     label?: string;
     description?: string;
     qualifiedFieldName?: string;
-    role?: 'metric';
+    qualifiedEntityName?: string;
+    entityId?: string;
+    entityName?: string;
+    entityType?: EntityType;
+    role?: 'groupby' | 'metric' | 'sortby' | 'pivotby' | 'detail';
     expression?: string;
     calculatedFormula?: CalculatedFieldFormula;
     format?: FormatSpec;
@@ -2515,7 +2530,7 @@ export declare type TDataLabelsConfig = {
     display?: 'auto' | boolean;
     formatMode?: 'inherit' | 'override';
     /** @deprecated Use formatMode + formatOptions.type */
-    format?: 'auto' | 'number' | 'currency' | 'percent' | 'date' | 'scientific' | 'none';
+    format?: 'auto' | 'number' | 'currency' | 'percent' | 'date' | 'scientific' | 'duration' | 'none';
     formatOptions?: TFormatOptions;
     font?: {
         size?: number;
@@ -2666,7 +2681,7 @@ declare type TFilter = {
 declare type TFilterValue = FilterForString | FilterForEqual | FilterForCompare | FilterForBetween | FilterForIn | FilterForNull | FilterForDate;
 
 export declare type TFormatOptions = {
-    type?: 'auto' | 'number' | 'currency' | 'percent' | 'scientific' | 'date';
+    type?: 'auto' | 'number' | 'currency' | 'percent' | 'scientific' | 'date' | 'duration';
     decimalPlaces?: number;
     minimumFractionDigits?: number;
     maximumFractionDigits?: number;
@@ -2683,6 +2698,11 @@ export declare type TFormatOptions = {
     timezone?: string;
     sourceTimezone?: string;
     relative?: boolean;
+    durationInputUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    durationDisplayStyle?: 'compact' | 'digital' | 'long';
+    durationLargestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    durationSmallestUnit?: 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+    durationMaxUnits?: number;
 };
 
 export declare type TFrame = {

package/dist/types/data-app-sdk.d.ts

@@ -0,0 +1,379 @@
+import { JSX } from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+export declare function createSemaphorDataAppExecutor(): SemaphorDataAppExecutor;
+
+export declare function hasSemaphorInputValue(value: unknown): boolean;
+
+export declare function normalizeSemaphorInputOptions(options?: Array<{
+    label: string;
+    value: SemaphorDataAppOptionValue;
+} | SemaphorDataAppOptionValue>): {
+    label: string;
+    value: SemaphorDataAppOptionValue;
+}[];
+
+declare type SemaphorAnalyticsIntent = SemaphorMetricIntent | SemaphorRecordsIntent | SemaphorInputOptionsIntent | SemaphorSqlIntent;
+
+export declare type SemaphorDataAppControlInputSpec<TValue extends SemaphorDataAppInputValue = SemaphorDataAppInputValue> = SemaphorDataAppInputBase<TValue> & {
+    kind: 'control';
+    role: SemaphorDataAppControlRole;
+};
+
+export declare type SemaphorDataAppControlRole = 'grain' | 'metric' | 'dimension' | 'aggregation' | 'sqlParam';
+
+export declare type SemaphorDataAppExecutor = {
+    executeMetric(intent: SemaphorMetricIntent, context: SemaphorDataAppExecutorContext): Promise<SemaphorDataAppMetricData>;
+    executeRecords<TRecord extends Record<string, unknown> = Record<string, unknown>>(intent: SemaphorRecordsIntent, context: SemaphorDataAppExecutorContext): Promise<SemaphorDataAppRecordsData<TRecord>>;
+    executeInputOptions(intent: Extract<SemaphorAnalyticsIntent, {
+        kind: 'inputOptions';
+    }>, context: SemaphorDataAppExecutorContext): Promise<SemaphorDataAppInputOptionsData>;
+};
+
+export declare type SemaphorDataAppExecutorContext = {
+    token?: string;
+    apiBaseUrl?: string;
+    activeInputs?: SemaphorDataAppInputSnapshot[];
+};
+
+export declare type SemaphorDataAppFieldSpec = string | SemaphorFieldRef;
+
+export declare type SemaphorDataAppFilterInputSpec<TValue extends SemaphorDataAppInputValue = SemaphorDataAppInputValue> = SemaphorDataAppInputBase<TValue> & {
+    kind: 'filter';
+    field: SemaphorDataAppFieldSpec;
+    operator?: SemaphorInputOperator;
+    multi?: boolean;
+    source?: SemaphorSourceRef;
+};
+
+declare type SemaphorDataAppInputBase<TValue extends SemaphorDataAppInputValue> = {
+    id: string;
+    label?: string;
+    value?: TValue;
+    defaultValue?: TValue;
+    onValueChange?: (value: TValue | undefined) => void;
+    options?: Array<SemaphorDataAppInputOption | SemaphorDataAppOptionValue>;
+};
+
+export declare type SemaphorDataAppInputHandle<TValue extends SemaphorDataAppInputValue = SemaphorDataAppInputValue> = {
+    id: string;
+    kind: 'filter' | 'control';
+    label?: string;
+    field?: SemaphorFieldRef;
+    operator?: SemaphorInputOperator;
+    source?: SemaphorSourceRef;
+    controlRole?: SemaphorDataAppControlRole;
+    value: TValue | undefined;
+    options: SemaphorDataAppInputOption[];
+    isActive: boolean;
+    setValue(value: TValue | undefined): void;
+    clear(): void;
+    toAnalyticsInput(): SemaphorDataAppInputSnapshot<TValue>;
+};
+
+export declare type SemaphorDataAppInputOption = {
+    label: string;
+    value: SemaphorDataAppOptionValue;
+    count?: number;
+};
+
+export declare type SemaphorDataAppInputOptionsData = {
+    options: SemaphorDataAppInputOption[];
+};
+
+export declare type SemaphorDataAppInputOptionsResult = SemaphorDataAppQueryState & SemaphorDataAppInputOptionsData & {
+    id?: string;
+    intent?: Extract<SemaphorAnalyticsIntent, {
+        kind: 'inputOptions';
+    }>;
+};
+
+export declare type SemaphorDataAppInputOptionsSpec = SemaphorDataAppSourceSpec & {
+    id?: string;
+    label?: string;
+    field: SemaphorDataAppFieldSpec;
+    search?: string;
+    limit?: number;
+};
+
+export declare type SemaphorDataAppInputReference = SemaphorInputBinding | SemaphorDataAppInputSnapshot | SemaphorDataAppInputHandle;
+
+export declare type SemaphorDataAppInputSnapshot<TValue extends SemaphorDataAppInputValue = SemaphorDataAppInputValue> = SemaphorInputBinding & {
+    kind: 'filter' | 'control';
+    label?: string;
+    value?: TValue;
+    isActive: boolean;
+    operator?: SemaphorInputOperator;
+    source?: SemaphorSourceRef;
+    controlRole?: SemaphorDataAppControlRole;
+};
+
+export declare type SemaphorDataAppInputSpec<TValue extends SemaphorDataAppInputValue = SemaphorDataAppInputValue> = SemaphorDataAppFilterInputSpec<TValue> | SemaphorDataAppControlInputSpec<TValue>;
+
+export declare type SemaphorDataAppInputValue = SemaphorDataAppScalar | SemaphorDataAppScalar[];
+
+export declare type SemaphorDataAppMetricComparison = 'none' | 'previous_period' | 'same_period_last_year' | 'previous_year' | {
+    kind: 'previous_period' | 'previous_year' | 'target';
+    targetValue?: number;
+};
+
+export declare type SemaphorDataAppMetricData = {
+    value: number | string | null;
+    metrics?: Record<string, number | string | null>;
+    comparisonValue?: number | string | null;
+    delta?: number | null;
+    deltaPercent?: number | null;
+    records?: Array<Record<string, unknown>>;
+};
+
+export declare type SemaphorDataAppMetricResult = SemaphorDataAppQueryState & SemaphorDataAppMetricData & {
+    id?: string;
+    intent?: SemaphorMetricIntent;
+};
+
+export declare type SemaphorDataAppMetricSpec = SemaphorDataAppSourceSpec & {
+    id?: string;
+    label?: string;
+    metric: string;
+    metrics?: string[];
+    dateField?: SemaphorDataAppFieldSpec;
+    timeGrain?: SemaphorTimeGrain;
+    dimensions?: SemaphorDataAppFieldSpec[];
+    comparison?: SemaphorDataAppMetricComparison;
+    inputs?: SemaphorDataAppInputReference[];
+    limit?: number;
+};
+
+export declare type SemaphorDataAppNonEmptyArray<T> = [T, ...T[]];
+
+export declare type SemaphorDataAppOptionValue = string | number | boolean;
+
+export declare function SemaphorDataAppProvider({ token, apiBaseUrl, executor, children, }: SemaphorDataAppProviderProps): JSX.Element;
+
+export declare type SemaphorDataAppProviderProps = SemaphorDataAppExecutorContext & {
+    executor?: SemaphorDataAppExecutor;
+    children: ReactNode;
+};
+
+export declare type SemaphorDataAppQueryState = {
+    status: SemaphorDataAppQueryStatus;
+    isLoading: boolean;
+    error: Error | null;
+};
+
+export declare type SemaphorDataAppQueryStatus = 'idle' | 'loading' | 'success' | 'error';
+
+declare type SemaphorDataAppRecordsBaseSpec = SemaphorDataAppSourceSpec & {
+    id?: string;
+    label?: string;
+    dateField?: SemaphorDataAppFieldSpec;
+    timeGrain?: SemaphorTimeGrain;
+    orderBy?: SemaphorDataAppRecordsOrderBy;
+    inputs?: SemaphorDataAppInputReference[];
+    limit?: number;
+};
+
+export declare type SemaphorDataAppRecordsData<TRecord extends Record<string, unknown> = Record<string, unknown>> = {
+    records: TRecord[];
+    columns?: Array<{
+        name: string;
+        label?: string;
+        dataType?: SemaphorFieldRef['dataType'];
+        role?: SemaphorFieldRef['role'];
+    }>;
+    rowCount?: number;
+};
+
+export declare type SemaphorDataAppRecordsOrderBy = {
+    field: string;
+    direction: 'asc' | 'desc';
+};
+
+export declare type SemaphorDataAppRecordsResult<TRecord extends Record<string, unknown> = Record<string, unknown>> = SemaphorDataAppQueryState & SemaphorDataAppRecordsData<TRecord> & {
+    id?: string;
+    intent?: SemaphorRecordsIntent;
+};
+
+declare type SemaphorDataAppRecordsSelectorSpec = {
+    fields: SemaphorDataAppNonEmptyArray<SemaphorDataAppFieldSpec>;
+    dimensions?: SemaphorDataAppFieldSpec[];
+    measures?: string[];
+} | {
+    fields?: SemaphorDataAppFieldSpec[];
+    dimensions: SemaphorDataAppNonEmptyArray<SemaphorDataAppFieldSpec>;
+    measures?: string[];
+} | {
+    fields?: SemaphorDataAppFieldSpec[];
+    dimensions?: SemaphorDataAppFieldSpec[];
+    measures: SemaphorDataAppNonEmptyArray<string>;
+};
+
+export declare type SemaphorDataAppRecordsSpec = SemaphorDataAppRecordsBaseSpec & SemaphorDataAppRecordsSelectorSpec;
+
+export declare type SemaphorDataAppRuntime = SemaphorDataAppExecutorContext & {
+    executor?: SemaphorDataAppExecutor;
+};
+
+export declare type SemaphorDataAppScalar = string | number | boolean | null;
+
+export declare type SemaphorDataAppSourceSpec = {
+    source: SemaphorSourceRef;
+    domainId?: never;
+    dataset?: never;
+    datasetName?: never;
+    datasetId?: never;
+    connectionId?: never;
+} | {
+    source?: never;
+    domainId: string;
+    dataset?: string;
+    datasetName?: string;
+    datasetId?: string;
+    connectionId?: string;
+    sourceLabel?: string;
+};
+
+declare type SemaphorDialect = 'semantic' | 'postgres' | 'mysql' | 'snowflake' | 'bigquery' | 'redshift' | 'duckdb' | 'sqlite' | 'unknown';
+
+declare type SemaphorFieldRef = {
+    name: string;
+    label?: string;
+    role?: 'dimension' | 'measure' | 'date' | 'id' | 'unknown';
+    dataType?: 'string' | 'number' | 'boolean' | 'date' | 'datetime' | 'unknown';
+    source?: SemaphorSourceRef;
+};
+
+declare type SemaphorInputBinding = {
+    inputId: string;
+    field?: SemaphorFieldRef;
+};
+
+declare type SemaphorInputOperator = '=' | '!=' | 'in' | 'not_in' | 'contains' | 'between' | '>' | '>=' | '<' | '<=';
+
+declare type SemaphorInputOptionsIntent = {
+    kind: 'inputOptions';
+    version?: SemaphorProtocolVersion;
+    id?: string;
+    label?: string;
+    source: SemaphorSourceRef;
+    field: SemaphorFieldRef;
+    search?: string;
+    limit?: number;
+};
+
+declare type SemaphorMetricIntent = {
+    kind: 'metric';
+    version?: SemaphorProtocolVersion;
+    id?: string;
+    source: SemaphorSourceRef;
+    metric: string;
+    metrics?: string[];
+    label?: string;
+    dateField?: SemaphorFieldRef;
+    timeGrain?: SemaphorTimeGrain;
+    dimensions?: SemaphorFieldRef[];
+    comparison?: {
+        kind: 'previous_period' | 'previous_year' | 'target';
+        targetValue?: number;
+    };
+    inputs?: SemaphorInputBinding[];
+    limit?: number;
+};
+
+declare type SemaphorProtocolVersion = 1;
+
+declare type SemaphorRecordsIntent = {
+    kind: 'records';
+    version?: SemaphorProtocolVersion;
+    source: SemaphorSourceRef;
+    id?: string;
+    label?: string;
+    fields: SemaphorFieldRef[];
+    measures?: string[];
+    dateField?: SemaphorFieldRef;
+    timeGrain?: SemaphorTimeGrain;
+    limit?: number;
+    orderBy?: {
+        field: string;
+        direction: 'asc' | 'desc';
+    };
+    inputs?: SemaphorInputBinding[];
+};
+
+declare type SemaphorSourceRef = {
+    kind: 'semantic';
+    domainId: string;
+    datasetName: string;
+    datasetId?: string;
+    label?: string;
+    connectionId?: string;
+} | {
+    kind: 'physical';
+    connectionId: string;
+    tableName: string;
+    databaseName?: string;
+    schemaName?: string;
+    label?: string;
+    dialect?: SemaphorDialect;
+} | {
+    kind: 'sql';
+    connectionId: string;
+    sql: string;
+    dialect?: SemaphorDialect;
+    label?: string;
+};
+
+declare type SemaphorSqlIntent = {
+    kind: 'sql';
+    version?: SemaphorProtocolVersion;
+    id?: string;
+    label?: string;
+    source: Extract<SemaphorSourceRef, {
+        kind: 'sql' | 'physical';
+    }>;
+    sql?: string;
+    parameters?: Record<string, unknown>;
+    pythonCode?: string;
+    limit?: number;
+    rationale?: string;
+    fields?: SemaphorFieldRef[];
+    inputs?: SemaphorInputBinding[];
+};
+
+declare type SemaphorTimeGrain = 'hour' | 'day' | 'week' | 'month' | 'quarter' | 'year';
+
+export declare function toSemaphorActiveInputSnapshots(inputs: SemaphorDataAppInputReference[] | undefined): SemaphorDataAppInputSnapshot[];
+
+export declare function toSemaphorInputBinding(input: SemaphorDataAppInputReference): SemaphorInputBinding;
+
+export declare function toSemaphorInputBindings(inputs: SemaphorDataAppInputReference[] | undefined): SemaphorInputBinding[] | undefined;
+
+export declare function toSemaphorInputOptionsIntent(spec: SemaphorDataAppInputOptionsSpec): Extract<SemaphorAnalyticsIntent, {
+    kind: 'inputOptions';
+}>;
+
+export declare function toSemaphorInputSnapshots(inputs: SemaphorDataAppInputReference[] | undefined): SemaphorDataAppInputSnapshot[];
+
+export declare function toSemaphorInputSpec<TValue extends SemaphorDataAppInputValue = SemaphorDataAppInputValue>(spec: SemaphorDataAppInputSpec<TValue>): SemaphorInputBinding & {
+    kind: SemaphorDataAppInputSpec['kind'];
+    label?: string;
+    field?: SemaphorFieldRef;
+    operator?: SemaphorInputOperator;
+    source?: SemaphorSourceRef;
+};
+
+export declare function toSemaphorMetricIntent(spec: SemaphorDataAppMetricSpec): SemaphorMetricIntent;
+
+export declare function toSemaphorRecordsIntent(spec: SemaphorDataAppRecordsSpec): SemaphorRecordsIntent;
+
+export declare function useSemaphorDataAppRuntime(): SemaphorDataAppRuntime;
+
+export declare function useSemaphorInput<TValue extends SemaphorDataAppInputValue = SemaphorDataAppInputValue>(spec: SemaphorDataAppInputSpec<TValue>): SemaphorDataAppInputHandle<TValue>;
+
+export declare function useSemaphorInputOptions(spec: SemaphorDataAppInputOptionsSpec): SemaphorDataAppInputOptionsResult;
+
+export declare function useSemaphorMetric(spec: SemaphorDataAppMetricSpec): SemaphorDataAppMetricResult;
+
+export declare function useSemaphorRecords<TRecord extends Record<string, unknown> = Record<string, unknown>>(spec: SemaphorDataAppRecordsSpec): SemaphorDataAppRecordsResult<TRecord>;
+
+export { }

package/dist/types/format-utils.d.ts

@@ -107,6 +107,29 @@ export declare interface DateFormatOptions {
     locale?: string;
 }
 
+export declare type DurationDisplayStyle = 'compact' | 'digital' | 'long';
+
+export declare interface DurationFormatOptions {
+    /** Unit represented by the raw numeric value. */
+    inputUnit?: DurationUnit;
+    /** Display style, e.g. "6min 32s", "06:32", or "6 minutes 32 seconds". */
+    outputStyle?: DurationDisplayStyle;
+    /** Largest unit to show. Defaults to day. */
+    largestUnit?: DurationUnit;
+    /** Smallest unit to show. Defaults to second. */
+    smallestUnit?: DurationUnit;
+    /** Maximum non-zero unit parts to show for compact/long output. */
+    maxUnits?: number;
+    /** Add prefix string before the formatted duration. */
+    prefix?: string;
+    /** Add suffix string after the formatted duration. */
+    suffix?: string;
+    /** Show negative durations in parentheses instead of a minus sign. */
+    negativeInParentheses?: boolean;
+}
+
+export declare type DurationUnit = 'millisecond' | 'second' | 'minute' | 'hour' | 'day';
+
 /**
  * Escape a value for CSV output (RFC 4180 compliant)
  * Wraps in quotes if value contains delimiter, quotes, or newlines
@@ -181,6 +204,8 @@ export declare function formatCurrency(value: number | null | undefined, options
  */
 export declare const formatDate: (dateString: string | null | undefined, formatPattern: string | undefined, displayTimezone?: string, sourceTimezone?: string) => string;
 
+export declare function formatDuration(value: number | string | null | undefined, options?: DurationFormatOptions): string;
+
 /**
  * Format a number with locale-aware formatting
  */