@krak-stack/registry 0.1.39 → 0.1.41

package/README.md

@@ -98,6 +98,164 @@ if (!import.meta.env.SSR) {
 }
 ```
 
+### Named events and page views
+
+For workers, workflows, or CLIs without an HTTP server, provide `ServerOtlp.layer`
+from `@krak-stack/registry/opentelemetry/server`. `HttpApiOtlp.layer` already
+includes this layer alongside the browser proxy routes.
+
+```ts
+import { Effect } from "effect";
+import { ServerOtlp } from "@krak-stack/registry/opentelemetry/server";
+
+const program = ServerOtlp.track("app.order.completed", {
+  "order.id": "order-123",
+}).pipe(Effect.provide(ServerOtlp.layer));
+```
+
+Enable server events with `OTEL_LOGS_EXPORTER=otlp`, `OTEL_SERVICE_NAME`, and
+`OTEL_EXPORTER_OTLP_ENDPOINT` (the exporter appends `/v1/logs`), or an explicit
+`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`. Signal-specific headers override
+`OTEL_EXPORTER_OTLP_HEADERS`; `OTEL_SDK_DISABLED=true` disables export. Use a
+long-lived application runtime to retain batching; dispose it on shutdown to
+flush pending events.
+
+Browser events are separately opt-in and do not enable application log export:
+
+```ts
+BrowserOtlp.layer({ serviceName: "my-app-web", events: {} });
+
+// Effects use the active BrowserOtlp.layer, even from a different calling runtime.
+const telemetry = Effect.gen(function* () {
+  yield* BrowserOtlp.track("app.checkout.started", {
+    "checkout.source": "cart",
+  });
+  yield* BrowserOtlp.page({
+    name: "Documentation",
+    category: "Docs",
+    path: "/docs",
+  });
+});
+```
+
+With `events: {}`, page views are automatic: one when the layer starts, then one
+for each pathname change through `pushState`, `replaceState`, or `popstate`
+(back/forward). Repeated same-path changes and query/hash-only changes are ignored.
+History hooks and listeners are scoped and restored on disposal. Tracking follows
+URL changes, not framework loader completion. The first page may be anonymous if
+identity has not been set yet; identify does not retroactively change it.
+
+Set `events: { pageViews: false }` to disable automatic tracking while retaining custom events.
+Then call `page` (`pageView` alias) manually for route templates or application-specific
+navigation timing. Do not also manually emit the same automatic page view.
+Without `path`, it reads `location.pathname` when executed. It emits the
+application-defined event `browser.page_view` with required attribute `url.path`,
+stripping query strings and fragments. Supply sanitized paths or route templates
+when paths contain personal information. No cookies or visitor/session IDs are
+created. Only the pathname is captured; paths may still contain personal IDs.
+
+### Browser identity
+
+Call `BrowserOtlp.identify` when auth state becomes available or changes, and
+`BrowserOtlp.identify(null)` on logout. These remain Effects, but the caller does not need
+the browser exporter's services in its own runtime:
+
+```ts
+const telemetry = Effect.gen(function* () {
+  yield* BrowserOtlp.identify({
+    userId: "user-123",
+    organizationId: "org-123",
+  });
+  yield* BrowserOtlp.track("app.checkout.started");
+  yield* BrowserOtlp.page({ path: "/checkout" });
+  yield* BrowserOtlp.identify(null);
+});
+```
+
+Identity is in memory per telemetry runtime, not cookies or local storage.
+`identify` is best-effort and has no typed failure: invalid identity leaves the
+previous identity unchanged and logs a warning without including supplied values.
+`identify` replaces the complete identity; omitting an organization clears the
+previous organization. It emits no event. Identity is copied into each future
+event when recorded; changes and resets do not rewrite queued events. Identified
+user/org attributes override per-call properties/options, while scoped log
+annotations take precedence over identified identity. This applies only to event
+telemetry, not automatic trace/log exporters, API request headers, or authorization.
+Browser identity is client-supplied and untrusted; use trusted server events for
+billing, authorization, audit trails, or tenant-isolated reporting. Re-identify
+after a reload and update identity before recording events after an auth or
+organization change. The OTLP proxy remains passthrough and never enriches identity.
+
+Initialize the browser layer once on the application's long-lived runtime. After
+it starts, `Effect.runPromise(BrowserOtlp.identify(...))` and
+`Effect.runPromise(BrowserOtlp.track(...))` work from ordinary application code.
+Event methods retain typed validation errors and the calling fiber's trace/log
+context; `identify` handles validation failures internally.
+Calls executed before startup or after disposal are no-ops; nothing is buffered.
+If several browser layers are active, calls target the most recently started one;
+use a single browser layer in normal applications. There is no analytics bridge,
+React hook, or automatic identification.
+
+### Event options
+
+Both environments accept
+`track(name, properties?, options?)`. Common options are explicit and per-call,
+so server requests never share mutable visitor state:
+
+```ts
+const telemetry = Effect.gen(function* () {
+  yield* ServerOtlp.track(
+    "app.order.completed",
+    { "order.total": 49 },
+    {
+      sessionId: "session-123",
+      messageId: "order-123-completed",
+      context: { "organization.id": "org-123", "app.locale": "en" },
+    },
+  );
+});
+```
+
+`context` and event properties become flat OTLP attributes; properties override
+context on collision. Options `userId`, `anonymousId`, `sessionId`, and `messageId`
+map to `user.id`, `analytics.anonymous_id`, `session.id`, and `log.record.uid`,
+overriding properties with the same keys. Scoped `Effect.annotateLogs` annotations
+are inherited automatically and take precedence over all per-call attributes.
+In authenticated server handlers, `AuthMiddleware` already supplies `user.id` and
+`organization.id`, so do not repeat them in `.track()` calls. Background jobs and
+browser code can provide identity explicitly when needed. Annotations remain
+fiber-scoped; no identity state is persisted by the event service.
+Identifiers are optional; callers own
+consent and identity lifecycle. Message IDs aid correlation, not guaranteed
+deduplication. Optional `timestamp` accepts an Effect `DateTime.Utc` for delayed
+events; the SDK still sets observed time to the time of recording. There is no
+clock-skew correction. `page` accepts `properties` and these same `options`, plus
+optional `name` and `category` mapped to application-defined
+`analytics.page.name` and `analytics.page.category` attributes. It always owns
+the sanitized `url.path`. The `analytics.*` fields and `browser.page_view` name
+are project conventions, not standardized OpenTelemetry analytics semantics.
+Group, Alias, profile storage, destination routing, and automatic
+collection of IPs, user agents, page titles, referrers, and full URLs are not
+implemented.
+
+Both `.track(name, attributes?)` methods follow the
+[OpenTelemetry event conventions](https://opentelemetry.io/docs/specs/semconv/general/events/):
+records have the native `eventName` field, an occurrence timestamp, INFO severity
+number (9), flat structured attributes, and no body. The SDK sets observed time
+when it records the occurrence. Events inherit active trace/span IDs without
+creating spans. Use stable domain-qualified names with no dynamic identifiers;
+put changing values in attributes. Document each custom event's trigger and
+required/optional attributes; include `error.type` for failures. These conventions
+are still in development. Attribute values support strings, finite numbers,
+booleans, and homogeneous arrays of those values. Invalid inputs fail with an
+Effect schema error.
+
+The logs proxy must be enabled with `OTEL_LOGS_EXPORTER=otlp` for browser events.
+OTLP transports events; configure a collector and a logs backend such as Loki for
+storage and Grafana dashboards. Browser flushing on hidden/pagehide is best
+effort. Apply payload limits and rate limits at your public ingestion boundary,
+avoid sensitive attributes, and keep high-cardinality fields out of Loki labels.
+
 `@krak-stack/registry/service-notification` is the source-compatible direct
 dispatcher. Use the separate `@krak-stack/notifications` package for a durable
 inbox, package-owned migrations, persisted delivery jobs, retries, workers, and

package/dist/components/ui/data-table.d.ts

@@ -32,10 +32,10 @@ export interface DataTableListItemContext<TData> {
 }
 export interface DataTableListOptions {
     emptyLabel: ReactNode;
-    display?: "list" | "icon";
-    locale?: string;
-    messages?: DataTableMessageTranslations;
-    visibleCount?: number;
+    display?: "list" | "icon" | undefined;
+    locale?: string | undefined;
+    messages?: DataTableMessageTranslations | undefined;
+    visibleCount?: number | undefined;
 }
 export type DataTableListColumn<TData> = DataTableListOptions & {
     /** Includes items not loaded in the preview; the dropdown only shows supplied items. */
@@ -76,8 +76,8 @@ interface EditableDataTableListCellProps extends DataTableListOptions {
     totalCount?: number | undefined;
 }
 interface DataTableListCellActionsProps {
-    actionsLabel?: string;
-    itemActions?: readonly DataTableItemAction<DataTableListItem>[];
+    actionsLabel?: string | undefined;
+    itemActions?: readonly DataTableItemAction<DataTableListItem>[] | undefined;
 }
 export type DataTableListCellProps = DataTableListCellActionsProps & (EditableDataTableListCellProps | (DataTableListSummaryProps & {
     options?: never;
@@ -206,6 +206,23 @@ export type DataTablePaginationFeature = false | {
     rowCount: number;
     pageSizes?: readonly number[];
 };
+export interface DataTableExportAction {
+    id: string;
+    label: string;
+    icon?: ReactNode;
+    disabled?: boolean;
+    /** The app owns fetching, authorization, field selection, and downloading. */
+    onExport: () => void | Promise<void>;
+}
+export interface DataTableExportFeature {
+    baseName: string;
+    /** Both scopes operate only on rows already supplied to the table. */
+    scope?: "currentPage" | "filteredRows";
+    /** Set false to offer only app-provided actions. Defaults to true. */
+    builtIn?: boolean;
+    actions?: readonly DataTableExportAction[];
+    onError?: (error: unknown, action: DataTableExportAction) => void;
+}
 export interface DataTableFeatures<TData> {
     toolbar?: false | {
         /** Additional `MenubarMenu` controls rendered at the start of the toolbar. */
@@ -228,10 +245,7 @@ export interface DataTableFeatures<TData> {
         label?: string;
         items: readonly DataTableRowAction<TData>[];
     };
-    export?: false | {
-        baseName: string;
-        scope?: "currentPage" | "filteredRows";
-    };
+    export?: false | DataTableExportFeature;
     gallery?: false | {
         name: string;
         description?: string;
@@ -255,6 +269,7 @@ export type DataTableMessages = PaginationMessages & {
     export: string;
     exportCsv: string;
     exportJson: string;
+    exportFailed?: string;
     refresh: string;
     view: string;
     tableView: string;
@@ -295,6 +310,7 @@ export declare const dataTableMessages: (locale?: string, translations?: DataTab
     export: string;
     exportCsv: string;
     exportJson: string;
+    exportFailed: string;
     refresh: string;
     view: string;
     tableView: string;
@@ -332,6 +348,7 @@ export declare const dataTableMessages: (locale?: string, translations?: DataTab
     export: string;
     exportCsv: string;
     exportJson: string;
+    exportFailed: string;
     refresh: string;
     view: string;
     tableView: string;

package/dist/components/ui/data-table.js

@@ -993,6 +993,7 @@ var messages2 = {
     export: "Export",
     exportCsv: "CSV",
     exportJson: "JSON",
+    exportFailed: "Export failed. Please try again.",
     refresh: "Refresh",
     view: "View",
     tableView: "Table",
@@ -1024,6 +1025,7 @@ var messages2 = {
     export: "Exporter",
     exportCsv: "CSV",
     exportJson: "JSON",
+    exportFailed: "L’exportation a échoué. Veuillez réessayer.",
     refresh: "Rafraîchir",
     view: "Affichage",
     tableView: "Tableau",
@@ -1586,7 +1588,7 @@ var DataTableRowActions = ({
                 event.stopPropagation();
                 action.onClick(row);
               },
-              variant: action.variant,
+              variant: action.variant ?? "default",
               children: [
                 action.icon,
                 action.name
@@ -1641,6 +1643,9 @@ var DataTableToolbar = ({
   tableAtom
 }) => {
   const [store, setStore] = useTableAtom(tableAtom);
+  const exportPending = useRef(false);
+  const [exporting, setExporting] = useState(false);
+  const [exportFailed, setExportFailed] = useState(false);
   const { features, labels } = store.config;
   const model = deriveModel(store);
   const selectedRows = getSelectedRows(store, model);
@@ -1653,6 +1658,27 @@ var DataTableToolbar = ({
   const update = (next) => changeState(setStore, next);
   const visibleBulkActions = bulkActions ? bulkActions.items.filter((action) => !action.visible || action.visible(selectedRows)) : [];
   const exportRows = features.export && features.export.scope === "filteredRows" ? model.filteredRows : model.pageRows;
+  const exportFeature = features.export;
+  const exportActions = exportFeature ? exportFeature.actions ?? [] : [];
+  const builtInExport = exportFeature && exportFeature.builtIn !== false;
+  const canExport = builtInExport && exportRows.length > 0 || exportActions.some((action) => !action.disabled);
+  const runExport = async (action) => {
+    if (exportPending.current || action.disabled)
+      return;
+    exportPending.current = true;
+    setExporting(true);
+    setExportFailed(false);
+    try {
+      await action.onExport();
+    } catch (error) {
+      setExportFailed(true);
+      if (exportFeature)
+        exportFeature.onError?.(error, action);
+    } finally {
+      exportPending.current = false;
+      setExporting(false);
+    }
+  };
   return /* @__PURE__ */ jsxs8("div", {
     className: "flex flex-col gap-2 pb-4",
     children: [
@@ -1716,7 +1742,7 @@ var DataTableToolbar = ({
                       /* @__PURE__ */ jsx14(MenubarSeparator, {}),
                       visibleBulkActions.map((action) => /* @__PURE__ */ jsxs8(MenubarItem, {
                         onClick: () => action.onClick(selectedRows),
-                        variant: action.variant,
+                        variant: action.variant ?? "default",
                         children: [
                           action.icon,
                           action.name
@@ -1786,12 +1812,15 @@ var DataTableToolbar = ({
               children: [
                 /* @__PURE__ */ jsxs8(MenubarTrigger, {
                   "aria-label": labels.export,
-                  disabled: !exportRows.length,
+                  "aria-busy": exporting,
+                  disabled: exporting || !canExport,
                   children: [
-                    /* @__PURE__ */ jsx14(Download, {}),
+                    exporting ? /* @__PURE__ */ jsx14(RefreshCw, {
+                      className: "animate-spin"
+                    }) : /* @__PURE__ */ jsx14(Download, {}),
                     /* @__PURE__ */ jsx14("span", {
                       className: "hidden sm:inline",
-                      children: labels.export
+                      children: exporting ? labels.loading : labels.export
                     })
                   ]
                 }),
@@ -1803,23 +1832,38 @@ var DataTableToolbar = ({
                         children: labels.export
                       }),
                       /* @__PURE__ */ jsx14(MenubarSeparator, {}),
-                      /* @__PURE__ */ jsxs8(MenubarItem, {
-                        onClick: () => downloadCsv(model.visibleColumns.map(columnLabel), exportRows.map((row) => model.visibleColumns.map((column) => String(getDataTableExportValue(row, column, store.config.locale) ?? ""))), features.export ? features.export.baseName : "table"),
+                      builtInExport ? /* @__PURE__ */ jsxs8(Fragment, {
                         children: [
-                          /* @__PURE__ */ jsx14(FileText, {}),
-                          labels.exportCsv
+                          /* @__PURE__ */ jsxs8(MenubarItem, {
+                            disabled: exporting || !exportRows.length,
+                            onClick: () => downloadCsv(model.visibleColumns.map(columnLabel), exportRows.map((row) => model.visibleColumns.map((column) => String(getDataTableExportValue(row, column, store.config.locale) ?? ""))), features.export ? features.export.baseName : "table"),
+                            children: [
+                              /* @__PURE__ */ jsx14(FileText, {}),
+                              labels.exportCsv
+                            ]
+                          }),
+                          /* @__PURE__ */ jsxs8(MenubarItem, {
+                            disabled: exporting || !exportRows.length,
+                            onClick: () => downloadJson(exportRows.map((row) => Object.fromEntries(model.visibleColumns.map((column) => [
+                              column.id,
+                              getDataTableExportValue(row, column, store.config.locale)
+                            ]))), features.export ? features.export.baseName : "table"),
+                            children: [
+                              /* @__PURE__ */ jsx14(FileJson, {}),
+                              labels.exportJson
+                            ]
+                          })
                         ]
-                      }),
-                      /* @__PURE__ */ jsxs8(MenubarItem, {
-                        onClick: () => downloadJson(exportRows.map((row) => Object.fromEntries(model.visibleColumns.map((column) => [
-                          column.id,
-                          getDataTableExportValue(row, column, store.config.locale)
-                        ]))), features.export ? features.export.baseName : "table"),
+                      }) : null,
+                      builtInExport && exportActions.length ? /* @__PURE__ */ jsx14(MenubarSeparator, {}) : null,
+                      exportActions.map((action) => /* @__PURE__ */ jsxs8(MenubarItem, {
+                        disabled: exporting || action.disabled,
+                        onClick: () => void runExport(action),
                         children: [
-                          /* @__PURE__ */ jsx14(FileJson, {}),
-                          labels.exportJson
+                          action.icon,
+                          action.label
                         ]
-                      })
+                      }, action.id))
                     ]
                   })
                 })
@@ -1827,7 +1871,12 @@ var DataTableToolbar = ({
             }) : null
           ]
         })
-      })
+      }),
+      exportFeature && exportFailed ? /* @__PURE__ */ jsx14("p", {
+        role: "alert",
+        className: "text-destructive text-sm",
+        children: labels.exportFailed ?? dataTableMessages(store.config.locale).exportFailed
+      }) : null
     ]
   });
 };
@@ -2293,7 +2342,7 @@ var GroupActions = ({
         children: /* @__PURE__ */ jsx14(DropdownMenuGroup, {
           children: visible.map((action) => /* @__PURE__ */ jsxs8(DropdownMenuItem, {
             onClick: () => action.onClick(groupId),
-            variant: action.variant,
+            variant: action.variant ?? "default",
             children: [
               action.icon,
               " ",
@@ -2796,23 +2845,21 @@ var HydratedDataTable = ({
   setPersistedUiState,
   ...props
 }) => {
-  const transientUiAtomRef = useRef(null);
-  if (!transientUiAtomRef.current) {
+  const [transientUiAtom] = useState(() => {
     const grouping = props.features?.grouping;
-    transientUiAtomRef.current = Atom.make({
+    return Atom.make({
       ...transientUiFromState(DEFAULT_UI_STATE),
       grouping: grouping && grouping.initial ? grouping.initial : []
     });
-  }
-  const [transientUiState, setTransientUiState] = useAtom(transientUiAtomRef.current);
+  });
+  const [transientUiState, setTransientUiState] = useAtom(transientUiAtom);
   const uiState = useMemo(() => ({ ...persistedUiState, ...transientUiState }), [persistedUiState, transientUiState]);
   const setUiState = useCallback((state) => {
     setPersistedUiState(persistedUiFromState(state));
     setTransientUiState(transientUiFromState(state));
   }, [setPersistedUiState, setTransientUiState]);
   const validatedConfig = resolveConfig(props, (state) => setUiState(state));
-  const atomRef = useRef(null);
-  if (!atomRef.current) {
+  const [tableAtom] = useState(() => {
     const initial = {
       rowData: props.rowData,
       columnDefs: props.columnDefs,
@@ -2820,12 +2867,11 @@ var HydratedDataTable = ({
       state: initialPublicState(props, uiState),
       controlledState: props.state
     };
-    atomRef.current = Atom.make({
+    return Atom.make({
       ...initial,
       model: buildDataTableModel(initial)
     });
-  }
-  const tableAtom = atomRef.current;
+  });
   const setStore = useAtomSet(tableAtom);
   useLayoutEffect(() => {
     setStore((store) => {
@@ -2886,20 +2932,19 @@ var HydratedDataTable = ({
 };
 var DataTable = (props) => {
   const locale = useKrakstackLocale3(props.locale);
-  const persistedUiAtomRef = useRef(null);
-  if (!persistedUiAtomRef.current) {
+  const [persistedUiAtom] = useState(() => {
     const pathname = globalThis.window?.location.pathname ?? "/";
     const columnIds = normalizeDataTableColumns(props.columnDefs).map(({ id }) => id).join(",");
     const viewCapability = props.features?.gallery ? "gallery" : "table";
-    persistedUiAtomRef.current = Atom.kvs({
+    return Atom.kvs({
       mode: "async",
       runtime: dataTableStorageRuntime,
       key: `data-table:${pathname}:${columnIds}:${viewCapability}:ui`,
       schema: DataTablePersistedUiStateSchema,
       defaultValue: () => persistedUiFromState(DEFAULT_UI_STATE)
     });
-  }
-  const [persistedUiResult, setPersistedUiState] = useAtom(persistedUiAtomRef.current);
+  });
+  const [persistedUiResult, setPersistedUiState] = useAtom(persistedUiAtom);
   if (!AsyncResult.isSuccess(persistedUiResult) || AsyncResult.isWaiting(persistedUiResult)) {
     return /* @__PURE__ */ jsx14("div", {
       "aria-busy": "true",
@@ -3139,7 +3184,7 @@ var DataTableListMenu = ({
                       event.stopPropagation();
                       action.onClick(item);
                     },
-                    variant: action.variant,
+                    variant: action.variant ?? "default",
                     children: [
                       action.icon,
                       action.name

package/dist/components/ui/google-map.d.ts

@@ -22,6 +22,7 @@ export type GoogleMapMessages = {
     errorBody: string;
     zoomIn: string;
     zoomOut: string;
+    showArea: string;
 };
 export type GoogleMapMessageTranslations = Partial<Record<string, Partial<GoogleMapMessages>>>;
 export type GoogleMapProps = {
@@ -32,6 +33,8 @@ export type GoogleMapProps = {
     radius?: GoogleMapRadiusOptions | undefined;
     interactive?: boolean | undefined;
     zoomControls?: boolean | undefined;
+    fitRadius?: boolean | undefined;
+    fitPadding?: number | undefined;
     minZoom?: number | undefined;
     maxZoom?: number | undefined;
     className?: string | undefined;
@@ -55,11 +58,18 @@ type GoogleMapOptions = {
     zoomControl: boolean;
 };
 type GoogleMapInstance = {
+    fitBounds: (bounds: GoogleMapBounds, padding: number) => void;
     getZoom: () => number | undefined;
     setCenter: (center: GoogleMapPoint) => void;
     setOptions: (options: Partial<GoogleMapOptions>) => void;
     setZoom: (zoom: number) => void;
 };
+type GoogleMapBounds = {
+    north: number;
+    south: number;
+    east: number;
+    west: number;
+};
 type GoogleMarkerInstance = {
     setIcon: (icon?: string) => void;
     setMap: (map: GoogleMapInstance | null) => void;
@@ -67,6 +77,9 @@ type GoogleMarkerInstance = {
 };
 type GoogleCircleStyleOptions = Omit<GoogleMapRadiusOptions, "radiusMeters">;
 type GoogleCircleInstance = {
+    getBounds: () => {
+        toJSON: () => GoogleMapBounds;
+    } | undefined;
     setCenter: (center: GoogleMapPoint) => void;
     setMap: (map: GoogleMapInstance | null) => void;
     setOptions: (options: GoogleCircleStyleOptions) => void;
@@ -96,5 +109,5 @@ export type GoogleMapsApi = {
         };
     };
 };
-export declare function GoogleMap({ apiKey, center, zoom, marker, radius, interactive, zoomControls, minZoom, maxZoom, className, messages: messageOverrides, locale: localeOverride, }: GoogleMapProps): import("react").JSX.Element;
+export declare function GoogleMap({ apiKey, center, zoom, marker, radius, interactive, zoomControls, fitRadius, fitPadding, minZoom, maxZoom, className, messages: messageOverrides, locale: localeOverride, }: GoogleMapProps): import("react").JSX.Element;
 export {};