@lightdash/cli 0.3427.0 → 0.3429.0

package/dist/vendor/template/skill.md

@@ -1032,6 +1032,33 @@ const client = useLightdashClient();
 const user = await client.auth.getUser();
 ```
 
+### Shareable URL state
+
+The host page keeps a `?state=` query param in sync with the app's view state, so the
+browser's address bar is always a shareable link — a colleague who opens the link lands
+on the same view. **Use `useUrlState` instead of `useState` for every user-facing view
+control**: period/date-range selectors, active tab, segment pickers, sort toggles.
+
+```tsx
+import { useUrlState } from '@lightdash/query-sdk';
+
+const [period, setPeriod] = useUrlState('period', 'last_month');
+```
+
+- Drop-in `useState` shape (functional updates work). Values must be JSON-serializable.
+- Each control owns a stable string key; all keys share one map, so keep the total
+  small (≤ 4 KB serialized — oversized state stays in memory but stops persisting).
+- **Global filters are persisted automatically** — `useGlobalFilters()` already stores
+  its filters in URL state. Never wire filter state through `useUrlState` yourself.
+- **Treat the seeded value as untrusted.** It comes from a user-editable URL: validate
+  it before use and fall back to the default when it's not what you expect
+  (e.g. `PERIODS.includes(period) ? period : 'last_month'`).
+- Do NOT build "copy link" / "share" buttons — the host page owns the URL; sharing is
+  just copying the address bar.
+- Ephemeral UI state (open dropdowns, hover, modal visibility, in-progress form input)
+  stays in plain `useState` — only state that defines *which view* the user is looking
+  at belongs in the URL.
+
 ### External APIs
 
 When an app needs data from an external HTTP API (Stripe, a CRM, a weather
@@ -1182,6 +1209,8 @@ Use `<Loader2 className="animate-spin" />` from `lucide-react`, not skeletons. G
 
 > **Limitation by design:** A field that legitimately exists on multiple explores (e.g. `region` joined into both `orders` and `regional_sales`) won't cross-filter under this rule. That's the safe default. If the user explicitly asks for cross-explore linking on a shared dimension, you can call `addFilter` once per explore — but never broadcast a filter to all explores blindly.
 
+Global filters are automatically persisted to the host page URL (see [Shareable URL state](#shareable-url-state)) — filter selections survive reloads and shared links with no extra wiring.
+
 The filter context is pre-installed and wraps your app at the root. Import the hook from `@/lib/filters` — never reimplement it:
 
 ```tsx

package/dist/vendor/template/src/lib/filters.tsx

@@ -3,13 +3,38 @@ import {
     useCallback,
     useContext,
     useMemo,
-    useState,
     type ReactNode,
 } from 'react';
-import type { Filter } from '@lightdash/query-sdk';
+import { useUrlState, type Filter } from '@lightdash/query-sdk';
 
 export type ScopedFilter = Filter & { explore: string };
 
+// Global filters live in URL state so the host page's address bar is always a
+// shareable link to the current filtered view. The seeded value comes from a
+// user-editable URL — sanitize before trusting its shape, or malformed
+// entries flow into every metric query for the explore and fail the run.
+const isScalar = (v: unknown): v is string | number | boolean =>
+    typeof v === 'string' || typeof v === 'number' || typeof v === 'boolean';
+
+const sanitizeFilters = (value: unknown): ScopedFilter[] =>
+    Array.isArray(value)
+        ? value.filter((f): f is ScopedFilter => {
+              if (!f || typeof f !== 'object') return false;
+              const { explore, field, operator, value: filterValue } =
+                  f as ScopedFilter;
+              return (
+                  typeof explore === 'string' &&
+                  typeof field === 'string' &&
+                  typeof operator === 'string' &&
+                  operator.length > 0 &&
+                  (filterValue === undefined ||
+                      isScalar(filterValue) ||
+                      (Array.isArray(filterValue) &&
+                          filterValue.every(isScalar)))
+              );
+          })
+        : [];
+
 type FilterContextValue = {
     addFilter: (filter: ScopedFilter) => void;
     removeFilter: (filter: ScopedFilter) => void;
@@ -26,22 +51,35 @@ const sameTarget = (a: ScopedFilter, b: ScopedFilter) =>
     JSON.stringify(a.value) === JSON.stringify(b.value);
 
 export function FilterProvider({ children }: { children: ReactNode }) {
-    const [filters, setFilters] = useState<ScopedFilter[]>([]);
+    const [rawFilters, setFilters] = useUrlState<ScopedFilter[]>(
+        'globalFilters',
+        [],
+    );
+    const filters = useMemo(() => sanitizeFilters(rawFilters), [rawFilters]);
 
-    const addFilter = useCallback((filter: ScopedFilter) => {
-        setFilters((prev) => {
-            const exists = prev.some((f) => sameTarget(f, filter));
-            return exists
-                ? prev.filter((f) => !sameTarget(f, filter))
-                : [...prev, filter];
-        });
-    }, []);
+    const addFilter = useCallback(
+        (filter: ScopedFilter) => {
+            setFilters((prev) => {
+                const current = sanitizeFilters(prev);
+                const exists = current.some((f) => sameTarget(f, filter));
+                return exists
+                    ? current.filter((f) => !sameTarget(f, filter))
+                    : [...current, filter];
+            });
+        },
+        [setFilters],
+    );
 
-    const removeFilter = useCallback((filter: ScopedFilter) => {
-        setFilters((prev) => prev.filter((f) => !sameTarget(f, filter)));
-    }, []);
+    const removeFilter = useCallback(
+        (filter: ScopedFilter) => {
+            setFilters((prev) =>
+                sanitizeFilters(prev).filter((f) => !sameTarget(f, filter)),
+            );
+        },
+        [setFilters],
+    );
 
-    const clearFilters = useCallback(() => setFilters([]), []);
+    const clearFilters = useCallback(() => setFilters([]), [setFilters]);
 
     const filtersFor = useCallback(
         (explore: string): Filter[] =>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lightdash/cli",
-  "version": "0.3427.0",
+  "version": "0.3429.0",
   "description": "Lightdash CLI tool",
   "license": "MIT",
   "repository": {
@@ -41,8 +41,8 @@
     "unique-names-generator": "4.7.1",
     "uuid": "11.1.1",
     "yaml": "2.8.3",
-    "@lightdash/warehouses": "0.3427.0",
-    "@lightdash/common": "0.3427.0"
+    "@lightdash/common": "0.3429.0",
+    "@lightdash/warehouses": "0.3429.0"
   },
   "devDependencies": {
     "@types/inquirer": "8.2.4",