feat: allow filtering by locale in the translations page (#754)

Author: jeremydw

.changeset/khaki-lemons-report.md

@@ -0,0 +1,5 @@
+---
+'@blinkk/root-cms': patch
+---
+
+feat: allow filtering by locale in the translations page (#754)

packages/create-root/src/root-version.ts

@@ -1,2 +1,2 @@
 // This file is autogenerated by update-root-version.mjs.
-export const ROOT_VERSION = '2.2.1-alpha.7';
+export const ROOT_VERSION = '2.2.1';

packages/root-cms/ui/hooks/useQueryParam.tsx

@@ -0,0 +1,139 @@
+import {useState, useEffect, useCallback} from 'preact/hooks';
+
+interface UseQueryParamOptions<T> {
+  /** Whether to replace history entry instead of pushing new one. */
+  replace?: boolean;
+  /** Custom serialization function for complex values. */
+  serialize?: (value: T) => string;
+  /** Custom deserialization function for complex values. */
+  deserialize?: (value: string) => T;
+}
+
+type QueryParamSetter<T> = (value: T) => void;
+type QueryParamHookReturn<T> = [T, QueryParamSetter<T>];
+
+/**
+ * Hook that synchronizes state with a URL query parameter.
+ */
+export function useQueryParam<T = string>(
+  paramName: string,
+  defaultValue: T,
+  options: UseQueryParamOptions<T> = {}
+): QueryParamHookReturn<T> {
+  const {
+    replace = false,
+    serialize = (value: T) => String(value),
+    deserialize = (value: string) => value as T,
+  } = options;
+
+  // Get initial value from URL.
+  const getInitialValue = useCallback((): T => {
+    const urlParams = new URLSearchParams(window.location.search);
+    const paramValue = urlParams.get(paramName);
+
+    return paramValue !== null ? deserialize(paramValue) : defaultValue;
+  }, [paramName, defaultValue, deserialize]);
+
+  const [value, setValue] = useState(getInitialValue);
+
+  // Update state when URL changes (e.g., browser back/forward).
+  useEffect(() => {
+    const handlePopState = () => {
+      const urlParams = new URLSearchParams(window.location.search);
+      const paramValue = urlParams.get(paramName);
+      const newValue =
+        paramValue !== null ? deserialize(paramValue) : defaultValue;
+      setValue(newValue);
+    };
+
+    window.addEventListener('popstate', handlePopState);
+    return () => window.removeEventListener('popstate', handlePopState);
+  }, [paramName, defaultValue, deserialize]);
+
+  // Function to update both state and URL.
+  const updateParam = useCallback(
+    (newValue: T) => {
+      setValue(newValue);
+
+      const url = new URL(window.location.href);
+      const serializedValue = serialize(newValue);
+
+      if (serializedValue === String(defaultValue) || serializedValue === '') {
+        // Remove parameter if it's the default value or empty.
+        url.searchParams.delete(paramName);
+      } else {
+        url.searchParams.set(paramName, serializedValue);
+      }
+
+      const method = replace ? 'replaceState' : 'pushState';
+      window.history[method]({}, '', url.toString());
+    },
+    [paramName, defaultValue, serialize, replace]
+  );
+
+  return [value, updateParam];
+}
+
+export function useStringParam(
+  paramName: string,
+  defaultValue: string = ''
+): QueryParamHookReturn<string> {
+  return useQueryParam(paramName, defaultValue);
+}
+
+export function useNumberParam(
+  paramName: string,
+  defaultValue: number = 0
+): QueryParamHookReturn<number> {
+  return useQueryParam(paramName, defaultValue, {
+    serialize: (value: number) => String(value),
+    deserialize: (value: string) => {
+      const num = Number(value);
+      return isNaN(num) ? defaultValue : num;
+    },
+  });
+}
+
+export function useBooleanParam(
+  paramName: string,
+  defaultValue: boolean = false
+): QueryParamHookReturn<boolean> {
+  return useQueryParam(paramName, defaultValue, {
+    serialize: (value: boolean) => (value ? 'true' : 'false'),
+    deserialize: (value: string) => value === 'true',
+  });
+}
+
+export function useArrayParam(
+  paramName: string,
+  defaultValue: string[] = []
+): QueryParamHookReturn<string[]> {
+  return useQueryParam(paramName, defaultValue, {
+    serialize: (value: string[]) =>
+      Array.isArray(value) ? value.join(',') : '',
+    deserialize: (value: string) =>
+      value ? value.split(',').filter(Boolean) : defaultValue,
+  });
+}
+
+export function useJSONParam<T = Record<string, unknown>>(
+  paramName: string,
+  defaultValue: T
+): QueryParamHookReturn<T> {
+  return useQueryParam(paramName, defaultValue, {
+    serialize: (value: T) => {
+      try {
+        return JSON.stringify(value);
+      } catch {
+        return JSON.stringify(defaultValue);
+      }
+    },
+    deserialize: (value: string) => {
+      try {
+        return JSON.parse(value) as T;
+      } catch {
+        return defaultValue;
+      }
+    },
+  });
+}

packages/root-cms/ui/pages/DocTranslationsPage/DocTranslationsPage.css

@@ -77,7 +77,6 @@
 .DocTranslationsPage__Table th {
   border: 1px solid var(--color-border);
   background: #F8F9FA;
-  padding: 4px 10px;
   text-align: left;
 }
 
@@ -93,8 +92,31 @@
   box-sizing: border-box;
 }
 
+.DocTranslationsPage__Table__sourceCellHeader {
+  position: sticky;
+  left: 0;
+  z-index: 1;
+}
+
+.DocTranslationsPage__Table__headerLabel {
+  padding: 4px 10px;
+  display: block;
+  width: 100%;
+}
+
+.DocTranslationsPage__Table__localeHeader {
+  cursor: pointer;
+  position: relative;
+}
+
+.DocTranslationsPage__Table__headerTooltip {
+  width: 100%;
+}
+
 .DocTranslationsPage__Table__sourceCellWrap {
   background: #F8F9FA;
+  position: sticky;
+  left: 0;
 }
 
 .DocTranslationsPage__Table__sourceCell {

packages/root-cms/ui/pages/DocTranslationsPage/DocTranslationsPage.tsx

@@ -8,6 +8,7 @@ import {
 } from '@tabler/icons-preact';
 import {useEffect, useMemo, useRef, useState} from 'preact/hooks';
 import {Heading} from '../../components/Heading/Heading.js';
+import {useArrayParam} from '../../hooks/useQueryParam.js';
 import {Layout} from '../../layout/Layout.js';
 import {joinClassNames} from '../../utils/classes.js';
 import {
@@ -44,7 +45,8 @@ export function DocTranslationsPage(props: DocTranslationsPageProps) {
   const docId = `${collection}/${slug}`;
 
   const i18nConfig = window.__ROOT_CTX.rootConfig.i18n || {};
-  const i18nLocales = i18nConfig.locales || ['en'];
+  const defaultLocales = i18nConfig.locales || [];
+  const [i18nLocales, setI18nLocales] = useArrayParam('locale', defaultLocales);
 
   async function init() {
     try {
@@ -112,6 +114,17 @@ export function DocTranslationsPage(props: DocTranslationsPageProps) {
     setSaving(false);
   }
 
+  /** Toggles the locale in the URL and updates the state accordingly. */
+  function toggleLocale(locale: string) {
+    if (i18nLocales.length === defaultLocales.length) {
+      // Show only the selected locale.
+      setI18nLocales([locale]);
+    } else {
+      // Show all locales.
+      setI18nLocales(defaultLocales);
+    }
+  }
+
   return (
     <Layout>
       <div className="DocTranslationsPage">
@@ -177,6 +190,7 @@ export function DocTranslationsPage(props: DocTranslationsPageProps) {
               translationsMap={translationsMap}
               onChange={onChange}
               changesMap={changesMap}
+              onSelectLocale={(locale) => toggleLocale(locale)}
             />
           )}
         </div>
@@ -221,10 +235,13 @@ interface DocTranslationsPageTableProps {
   sourceStrings: string[];
   translationsMap: TranslationsMap;
   onChange: (source: string, locale: string, translation: string) => void;
+  onSelectLocale: (locale: string) => void;
   changesMap: Record<string, Translation>;
 }
 
 DocTranslationsPage.Table = (props: DocTranslationsPageTableProps) => {
+  const i18nConfig = window.__ROOT_CTX.rootConfig.i18n || {};
+  const allLocales = i18nConfig.locales || [];
   const sourceToTranslationsMap = useMemo(() => {
     const results: {[source: string]: Record<string, string>} = {};
     Object.values(props.translationsMap).forEach(
@@ -249,9 +266,32 @@ DocTranslationsPage.Table = (props: DocTranslationsPageTableProps) => {
       <table className="DocTranslationsPage__Table">
         <thead>
           <tr>
-            <th>source</th>
+            <th className="DocTranslationsPage__Table__sourceCellHeader">
+              <div className="DocTranslationsPage__Table__headerLabel">
+                source
+              </div>
+            </th>
             {props.locales.map((locale) => (
-              <th key={locale}>{locale}</th>
+              <th
+                key={locale}
+                onClick={() => props.onSelectLocale(locale)}
+                className="DocTranslationsPage__Table__localeHeader"
+              >
+                <Tooltip
+                  className="DocTranslationsPage__Table__headerTooltip"
+                  placement="start"
+                  withArrow
+                  label={
+                    props.locales.length === allLocales.length
+                      ? `Show only ${locale}`
+                      : 'Show all locales'
+                  }
+                >
+                  <div className="DocTranslationsPage__Table__headerLabel">
+                    {locale}
+                  </div>
+                </Tooltip>
+              </th>
             ))}
           </tr>
         </thead>