@groveback/ui 0.4.0 → 0.7.0

package/dist/SignIn.d.ts

@@ -10,6 +10,7 @@
  * through the same endpoints, and the same rate limits, as a hand-written form would.
  */
 import type { ReactNode } from 'react';
+import type { UiMessages } from './messages';
 import type { Doc } from './types';
 /**
  * The slice of the SDK's `client.auth` the gate uses. `login` may resolve with
@@ -32,6 +33,20 @@ export interface SignInProps {
     allowRegister?: boolean | undefined;
     /** Called with the user after a successful sign-in or registration. */
     onSignedIn?: ((user: Doc) => void) | undefined;
+    /**
+     * Language for the form's own words. Optional, and normally unnecessary: under
+     * `<GroveRoutes>` the gate reads the shell's locale like every other primitive.
+     *
+     * It exists for the mount that wraps the WHOLE router — `<SignIn><GroveRoutes /></SignIn>`,
+     * the way an app puts every page behind a session. That places the form above the provider
+     * carrying the locale, so a Spanish app came up with an English sign-in screen in front of
+     * translated pages. Absent, the gate falls back to the provider when there is one and then
+     * to the viewer's own languages, so that mount is now translated with no prop at all; pass
+     * one to drive it from the app's own switcher.
+     */
+    locale?: string | undefined;
+    /** Overrides for the form's words, merged over the shipped catalogue (see `messages.ts`). */
+    messages?: Partial<UiMessages> | undefined;
     /** What a signed-in viewer sees — normally the app's routes. */
     children: ReactNode;
 }

package/dist/components.d.ts

@@ -37,6 +37,8 @@ export declare function Stack(props: {
 }): import("react").JSX.Element;
 export declare function Grid(props: {
     columns: number;
+    /** Columns below the breakpoint; defaults to one. */
+    columnsMobile?: number;
     gap?: number;
     width?: keyof typeof WIDTH;
     children: ReactNode;
@@ -58,6 +60,23 @@ export declare function Text({ muted, children }: {
  * `href` is still real, which is what keeps middle-click, "open in new tab" and crawlers
  * working — the click handler only takes over the plain-left-click case.
  */
+/**
+ * The control a viewer switches language with.
+ *
+ * Renders nothing unless the app actually offers a choice: fewer than two document locales, or
+ * no `setLocale` on the context (an app driving `locale` as a fixed prop owns it — see
+ * `GroveRoutes`). So a monolingual app looks exactly as it did before this existed.
+ *
+ * It offers EVERY locale the document declares, not the ones this package ships chrome for.
+ * The screens' own words are the substance of the page and are translated into all of them;
+ * hiding a language because the package has no "Save" in it would hide a page that is fully
+ * translated apart from one button. Chrome the catalogue lacks degrades to English, which is
+ * a word rather than a blank — and the `messages` override is the documented way out (D86).
+ *
+ * A native `<select>`: keyboard and screen-reader behaviour for free, and a phone renders its
+ * own picker instead of a menu that has to be re-implemented for touch.
+ */
+export declare function LocaleSwitcher(): import("react").JSX.Element | null;
 export declare function Header(props: {
     brand?: ReactNode;
     brandHref?: string | undefined;

package/dist/index.d.ts

@@ -10,14 +10,15 @@
  * convention — this package is browser React bundled by `bun build`, not backend ESM, so the
  * convention buys nothing and extensionless is what every bundler agrees on.
  */
-import { Button, DataTable, Detail, Divider, Form, Grid, Header, Heading, Stack, Text } from './components';
+import { Button, DataTable, Detail, Divider, Form, Grid, Header, Heading, LocaleSwitcher, Stack, Text } from './components';
+import { localeLabel } from './locale';
 import { MarkdownField, renderMarkdown } from './MarkdownField';
 import { RelationSelect } from './RelationSelect';
 import { GroveRoutes, RouteIndex, matchRoute, resolveRoute } from './routes';
 import { SignIn } from './SignIn';
 import { uiMessagesFor } from './messages';
-import { GroveUiProvider, detectLocale, formatValue, resolveHref, useAction, useGroveUi, useMessages, usePageTitle, useUiMessages, useUiText } from './runtime';
-export { Button, DataTable, Detail, Divider, Form, Grid, GroveRoutes, GroveUiProvider, Header, Heading, MarkdownField, renderMarkdown, RelationSelect, RouteIndex, SignIn, Stack, Text, detectLocale, formatValue, matchRoute, resolveHref, resolveRoute, useAction, useGroveUi, useMessages, usePageTitle, uiMessagesFor, useUiMessages, useUiText, };
+import { GroveUiProvider, detectLocale, formatValue, resolveHref, useAction, useGroveUi, useMessages, usePageTitle, useStandaloneUiText, useUiMessages, useUiText } from './runtime';
+export { Button, DataTable, Detail, Divider, Form, Grid, GroveRoutes, GroveUiProvider, Header, Heading, LocaleSwitcher, MarkdownField, renderMarkdown, RelationSelect, RouteIndex, SignIn, Stack, Text, detectLocale, formatValue, localeLabel, matchRoute, resolveHref, resolveRoute, useAction, useGroveUi, useMessages, usePageTitle, useStandaloneUiText, uiMessagesFor, useUiMessages, useUiText, };
 export type { RelationSelectProps } from './RelationSelect';
 export type { GroveUiContext } from './runtime';
 export type { UiMessageKey, UiMessages } from './messages';

package/dist/index.js

@@ -1,6 +1,39 @@
 // src/components.tsx
 import { useCallback as useCallback2, useEffect as useEffect3, useRef as useRef2, useState as useState3 } from "react";
 
+// src/locale.ts
+var LOCALE_STORAGE_KEY = "grove.locale";
+function readStoredLocale(available) {
+  if (typeof window === "undefined")
+    return;
+  let stored = null;
+  try {
+    stored = window.localStorage.getItem(LOCALE_STORAGE_KEY);
+  } catch {
+    return;
+  }
+  if (stored === null)
+    return;
+  return available.includes(stored) ? stored : undefined;
+}
+function storeLocale(locale) {
+  if (typeof window === "undefined")
+    return;
+  try {
+    window.localStorage.setItem(LOCALE_STORAGE_KEY, locale);
+  } catch {}
+}
+function localeLabel(locale) {
+  try {
+    const names = new Intl.DisplayNames([locale], { type: "language" });
+    const label = names.of(locale);
+    if (label && label.toLowerCase() !== locale.toLowerCase()) {
+      return label.charAt(0).toUpperCase() + label.slice(1);
+    }
+  } catch {}
+  return locale;
+}
+
 // src/MarkdownField.tsx
 import { useState } from "react";
 
@@ -17,6 +50,7 @@ var EN = {
   "common.no": "No",
   "header.openMenu": "Open menu",
   "header.closeMenu": "Close menu",
+  "locale.label": "Language",
   "table.empty": "Nothing here yet.",
   "form.save": "Save",
   "form.saving": "Saving…",
@@ -62,6 +96,7 @@ var ES = {
   "common.no": "No",
   "header.openMenu": "Abrir menú",
   "header.closeMenu": "Cerrar menú",
+  "locale.label": "Idioma",
   "table.empty": "Todavía no hay nada.",
   "form.save": "Guardar",
   "form.saving": "Guardando…",
@@ -138,6 +173,12 @@ function useUiMessages() {
   const ctx = useGroveUi();
   return useMemo(() => ({ ...uiMessagesFor(ctx.locale), ...ctx.messages }), [ctx]);
 }
+function useStandaloneUiText(locale, overrides) {
+  const ctx = useGroveUi();
+  const active = locale ?? ctx.locale ?? detectLocale(Object.keys(UI_LOCALES));
+  const messages = { ...ctx.messages, ...overrides };
+  return useCallback((key) => messages[key] ?? uiMessagesFor(active)[key], [active, ctx.messages, overrides]);
+}
 function resolveHref(href, doc) {
   if (!doc)
     return href;
@@ -538,6 +579,7 @@ import { jsx as jsx4, jsxs as jsxs3, Fragment } from "react/jsx-runtime";
 var WIDTH_CLASS = { narrow: "w-[12%]", normal: "", wide: "w-[45%]" };
 var GAP = ["gap-0", "gap-1", "gap-2", "gap-3", "gap-4", "gap-5", "gap-6", "gap-7", "gap-8", "gap-9", "gap-10", "gap-11", "gap-12"];
 var COLUMNS = ["", "md:grid-cols-1", "md:grid-cols-2", "md:grid-cols-3", "md:grid-cols-4", "md:grid-cols-5", "md:grid-cols-6"];
+var BASE_COLUMNS = ["", "grid-cols-1", "grid-cols-2", "grid-cols-3", "grid-cols-4", "grid-cols-5", "grid-cols-6"];
 var WIDTH = { full: "w-full", container: "w-full max-w-5xl mx-auto", narrow: "w-full max-w-xl mx-auto" };
 var ALIGN = { start: "items-start", center: "items-center", end: "items-end", stretch: "items-stretch" };
 var JUSTIFY = { start: "justify-start", center: "justify-center", end: "justify-end", between: "justify-between" };
@@ -549,9 +591,13 @@ function Stack(props) {
   });
 }
 function Grid(props) {
-  const { columns, gap = 4, width, children } = props;
+  const { columns, columnsMobile, gap = 4, width, children } = props;
+  const mobile = Math.min(Math.max(columnsMobile ?? 1, 1), 6);
+  const desktop = Math.min(Math.max(columns, 1), 6);
   return /* @__PURE__ */ jsx4("div", {
-    className: cx("grid grid-cols-1", COLUMNS[Math.min(Math.max(columns, 1), 6)], GAP[Math.min(Math.max(gap, 0), 12)], width && WIDTH[width]),
+    "data-grove-cols": desktop,
+    "data-grove-cols-mobile": mobile,
+    className: cx("grid", BASE_COLUMNS[mobile], COLUMNS[desktop], GAP[Math.min(Math.max(gap, 0), 12)], width && WIDTH[width]),
     children
   });
 }
@@ -574,11 +620,30 @@ function Text({ muted, children }) {
     children
   });
 }
+function LocaleSwitcher() {
+  const { locale, locales, setLocale } = useGroveUi();
+  const t = useUiText();
+  if (!setLocale || !locales || locales.length < 2)
+    return null;
+  return /* @__PURE__ */ jsx4("select", {
+    "data-grove-locale": true,
+    "aria-label": t("locale.label"),
+    value: locale ?? locales[0],
+    onChange: (e) => setLocale(e.target.value),
+    className: cx(INPUT_CLASS, "py-1 pr-7 text-xs"),
+    children: locales.map((tag) => /* @__PURE__ */ jsx4("option", {
+      value: tag,
+      children: localeLabel(tag)
+    }, tag))
+  });
+}
 function Header(props) {
   const { brand, brandHref = "/", links, actions, sticky } = props;
   const dispatch = useAction();
   const t = useUiText();
+  const { onHeaderMounted } = useGroveUi();
   const [open, setOpen] = useState3(false);
+  useEffect3(() => onHeaderMounted?.(), [onHeaderMounted]);
   const go = useCallback2((href) => (e) => {
     if (e.defaultPrevented || e.metaKey || e.ctrlKey || e.shiftKey || e.altKey || e.button !== 0)
       return;
@@ -609,70 +674,76 @@ function Header(props) {
               children: link.label
             }, i))
           }) : null,
-          actions && actions.length > 0 ? /* @__PURE__ */ jsx4("div", {
-            "data-grove-nav-actions": true,
-            className: "ml-auto hidden items-center gap-2 md:flex",
-            children: actions.map((a, i) => /* @__PURE__ */ jsx4(Button, {
-              action: a.action,
-              variant: a.variant,
-              children: a.label
-            }, i))
-          }) : null,
-          hasNav ? /* @__PURE__ */ jsx4("button", {
-            type: "button",
-            "data-grove-nav-toggle": true,
-            "aria-label": t(open ? "header.closeMenu" : "header.openMenu"),
-            "aria-expanded": open,
-            onClick: () => setOpen((v) => !v),
-            className: "ml-auto inline-flex items-center justify-center rounded-md p-2 text-neutral-600 hover:bg-neutral-100 hover:text-neutral-900 md:hidden dark:text-neutral-400 dark:hover:bg-neutral-800 dark:hover:text-neutral-100",
-            children: /* @__PURE__ */ jsx4("svg", {
-              width: "20",
-              height: "20",
-              viewBox: "0 0 24 24",
-              fill: "none",
-              stroke: "currentColor",
-              strokeWidth: "2",
-              strokeLinecap: "round",
-              "aria-hidden": "true",
-              children: open ? /* @__PURE__ */ jsxs3(Fragment, {
-                children: [
-                  /* @__PURE__ */ jsx4("line", {
-                    x1: "18",
-                    y1: "6",
-                    x2: "6",
-                    y2: "18"
-                  }),
-                  /* @__PURE__ */ jsx4("line", {
-                    x1: "6",
-                    y1: "6",
-                    x2: "18",
-                    y2: "18"
-                  })
-                ]
-              }) : /* @__PURE__ */ jsxs3(Fragment, {
-                children: [
-                  /* @__PURE__ */ jsx4("line", {
-                    x1: "3",
-                    y1: "6",
-                    x2: "21",
-                    y2: "6"
-                  }),
-                  /* @__PURE__ */ jsx4("line", {
-                    x1: "3",
-                    y1: "12",
-                    x2: "21",
-                    y2: "12"
-                  }),
-                  /* @__PURE__ */ jsx4("line", {
-                    x1: "3",
-                    y1: "18",
-                    x2: "21",
-                    y2: "18"
+          /* @__PURE__ */ jsxs3("div", {
+            className: "ml-auto flex items-center gap-2",
+            children: [
+              actions && actions.length > 0 ? /* @__PURE__ */ jsx4("div", {
+                "data-grove-nav-actions": true,
+                className: "hidden items-center gap-2 md:flex",
+                children: actions.map((a, i) => /* @__PURE__ */ jsx4(Button, {
+                  action: a.action,
+                  variant: a.variant,
+                  children: a.label
+                }, i))
+              }) : null,
+              /* @__PURE__ */ jsx4(LocaleSwitcher, {}),
+              hasNav ? /* @__PURE__ */ jsx4("button", {
+                type: "button",
+                "data-grove-nav-toggle": true,
+                "aria-label": t(open ? "header.closeMenu" : "header.openMenu"),
+                "aria-expanded": open,
+                onClick: () => setOpen((v) => !v),
+                className: "inline-flex items-center justify-center rounded-md p-2 text-neutral-600 hover:bg-neutral-100 hover:text-neutral-900 md:hidden dark:text-neutral-400 dark:hover:bg-neutral-800 dark:hover:text-neutral-100",
+                children: /* @__PURE__ */ jsx4("svg", {
+                  width: "20",
+                  height: "20",
+                  viewBox: "0 0 24 24",
+                  fill: "none",
+                  stroke: "currentColor",
+                  strokeWidth: "2",
+                  strokeLinecap: "round",
+                  "aria-hidden": "true",
+                  children: open ? /* @__PURE__ */ jsxs3(Fragment, {
+                    children: [
+                      /* @__PURE__ */ jsx4("line", {
+                        x1: "18",
+                        y1: "6",
+                        x2: "6",
+                        y2: "18"
+                      }),
+                      /* @__PURE__ */ jsx4("line", {
+                        x1: "6",
+                        y1: "6",
+                        x2: "18",
+                        y2: "18"
+                      })
+                    ]
+                  }) : /* @__PURE__ */ jsxs3(Fragment, {
+                    children: [
+                      /* @__PURE__ */ jsx4("line", {
+                        x1: "3",
+                        y1: "6",
+                        x2: "21",
+                        y2: "6"
+                      }),
+                      /* @__PURE__ */ jsx4("line", {
+                        x1: "3",
+                        y1: "12",
+                        x2: "21",
+                        y2: "12"
+                      }),
+                      /* @__PURE__ */ jsx4("line", {
+                        x1: "3",
+                        y1: "18",
+                        x2: "21",
+                        y2: "18"
+                      })
+                    ]
                   })
-                ]
-              })
-            })
-          }) : null
+                })
+              }) : null
+            ]
+          })
         ]
       }),
       hasNav && open ? /* @__PURE__ */ jsxs3("div", {
@@ -1105,6 +1176,13 @@ function resolveRoute(routes, path) {
 function GroveRoutes(props) {
   const { routes, context, fallback, children, gate } = props;
   const [path, setPath] = useState4(() => window.location.pathname);
+  const offered = context?.locales;
+  const pinned = context?.locale;
+  const [chosen, setChosen] = useState4(() => pinned !== undefined || !offered || offered.length === 0 ? undefined : readStoredLocale(offered) ?? detectLocale(offered));
+  const setLocale = useCallback3((next) => {
+    setChosen(next);
+    storeLocale(next);
+  }, []);
   useEffect4(() => {
     const onPop = () => setPath(window.location.pathname);
     window.addEventListener("popstate", onPop);
@@ -1114,7 +1192,23 @@ function GroveRoutes(props) {
     window.history.pushState({}, "", href);
     setPath(href.split(/[?#]/)[0] ?? href);
   }, []);
-  const value = useMemo3(() => ({ ...context, navigate }), [context, navigate]);
+  const active = chosen ?? pinned;
+  useEffect4(() => {
+    if (active !== undefined)
+      document.documentElement.lang = active;
+  }, [active]);
+  const [headers, setHeaders] = useState4(0);
+  const onHeaderMounted = useCallback3(() => {
+    setHeaders((n) => n + 1);
+    return () => setHeaders((n) => n - 1);
+  }, []);
+  const value = useMemo3(() => ({
+    ...context,
+    navigate,
+    onHeaderMounted,
+    ...chosen !== undefined ? { locale: chosen } : {},
+    ...pinned === undefined && offered && offered.length > 1 ? { setLocale } : {}
+  }), [context, navigate, chosen, pinned, offered, setLocale, onHeaderMounted]);
   const hit = resolveRoute(routes, path);
   const isRoot = (path.replace(/\/+$/, "") || "/") === "/";
   const matched = hit ? hit.route.render(hit.params) : fallback ?? (isRoot ? /* @__PURE__ */ jsx5(RouteIndex, {
@@ -1125,7 +1219,11 @@ function GroveRoutes(props) {
     value,
     children: [
       children,
-      screen
+      screen,
+      headers === 0 ? /* @__PURE__ */ jsx5("div", {
+        className: "fixed right-3 bottom-3 z-50",
+        children: /* @__PURE__ */ jsx5(LocaleSwitcher, {})
+      }) : null
     ]
   });
 }
@@ -1191,8 +1289,16 @@ function RouteIndex({ routes }) {
 import { useCallback as useCallback4, useRef as useRef3, useState as useState5 } from "react";
 import { jsx as jsx6, jsxs as jsxs5, Fragment as Fragment2 } from "react/jsx-runtime";
 function SignIn(props) {
-  const { auth, title, allowRegister = typeof auth.register === "function", onSignedIn, children } = props;
-  const t = useUiText();
+  const {
+    auth,
+    title,
+    allowRegister = typeof auth.register === "function",
+    onSignedIn,
+    locale,
+    messages,
+    children
+  } = props;
+  const t = useStandaloneUiText(locale, messages);
   const [signedIn, setSignedIn] = useState5(() => auth.getTokens() !== null);
   const [mode, setMode] = useState5("login");
   const [email, setEmail] = useState5("");
@@ -1365,6 +1471,7 @@ export {
   GroveUiProvider,
   Header,
   Heading,
+  LocaleSwitcher,
   MarkdownField,
   RelationSelect,
   RouteIndex,
@@ -1373,6 +1480,7 @@ export {
   Text,
   detectLocale,
   formatValue,
+  localeLabel,
   matchRoute,
   renderMarkdown,
   resolveHref,
@@ -1382,6 +1490,7 @@ export {
   useGroveUi,
   useMessages,
   usePageTitle,
+  useStandaloneUiText,
   useUiMessages,
   useUiText
 };

package/dist/locale.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Remembering the viewer's chosen language.
+ *
+ * Pure and storage-aware but React-free, so the rules below are testable without a renderer —
+ * the same split the dashboard uses between its `i18n.ts` and `i18n-context.tsx`.
+ *
+ * Two rules matter more than the storage itself:
+ *  - A stored value is never trusted. It is user-editable, and it outlives the document that
+ *    produced it: an app that dropped `de` must not keep serving German because a browser
+ *    still remembers it. Anything not on offer falls back rather than sticking.
+ *  - Storage is allowed to fail. It throws in a private window and when site data is blocked,
+ *    and a language preference is never worth taking the page down for.
+ */
+/**
+ * Where the choice lives. Namespaced under `grove.` like the generated app's own
+ * `grove.session`, and deliberately NOT the dashboard's `groveback.ui.locale`: this ships
+ * INTO a user's app, which may be served from the same origin as nothing in particular.
+ */
+export declare const LOCALE_STORAGE_KEY = "grove.locale";
+/** The stored choice, if it is still one of `available`. */
+export declare function readStoredLocale(available: readonly string[]): string | undefined;
+/** Remember a choice. A failed write costs the memory, never the switch itself. */
+export declare function storeLocale(locale: string): void;
+/**
+ * How a language names ITSELF — "Español", not "Spanish". The person hunting for the switcher
+ * is the one who cannot read the language currently on screen, so every option is rendered in
+ * its own tongue.
+ *
+ * Document locales are arbitrary validated tags, so no shipped label table could cover them;
+ * `Intl.DisplayNames` knows them, and the raw tag is the honest fallback when it does not.
+ */
+export declare function localeLabel(locale: string): string;

package/dist/messages.d.ts

@@ -26,6 +26,8 @@ export interface UiMessages {
     'common.no': string;
     'header.openMenu': string;
     'header.closeMenu': string;
+    /** Accessible name of the language switcher — the options label themselves. */
+    'locale.label': string;
     'table.empty': string;
     'form.save': string;
     'form.saving': string;

package/dist/runtime.d.ts

@@ -21,6 +21,24 @@ export interface GroveUiContext {
     /** Confirmation gate for destructive actions; defaults to window.confirm. */
     confirm?: (message: string) => boolean | Promise<boolean>;
     locale?: string;
+    /**
+     * Every locale the document offers, default first — what a switcher puts on the menu.
+     * Absent, or shorter than two entries, means a monolingual app: no switcher renders.
+     */
+    locales?: readonly string[] | undefined;
+    /**
+     * Switches the app's language. Supplied by `GroveRoutes`, which holds the locale in state
+     * and persists the choice; absent when an app drives `locale` itself as a fixed prop, and
+     * `LocaleSwitcher` then renders nothing rather than offering a control that does nothing.
+     */
+    setLocale?: ((locale: string) => void) | undefined;
+    /**
+     * Called by `Header` while it is mounted — it returns its own cleanup, so the call site is
+     * a one-liner `useEffect`. The shell counts headers to decide whether to float a language
+     * switcher of its own: a document with no header, or a screen that opted out, renders none,
+     * and without this a multilingual app would ship a switcher nothing puts on the page.
+     */
+    onHeaderMounted?: (() => () => void) | undefined;
     currency?: string;
     /**
      * Overrides for the primitives' OWN strings (`messages.ts`) — the chrome an app never
@@ -51,6 +69,20 @@ export declare function uiText(ctx: GroveUiContext, key: UiMessageKey): string;
 export declare function useUiText(): (key: UiMessageKey) => string;
 /** The chrome catalogue in force — for the few places that need several keys at once. */
 export declare function useUiMessages(): UiMessages;
+/**
+ * The chrome translator for a component that may render OUTSIDE the provider.
+ *
+ * `SignIn` is the case this exists for: the generated app can mount it around the whole
+ * router (`<SignIn><GroveRoutes /></SignIn>`), which puts the form ABOVE the provider that
+ * carries the locale — so the sign-in screen of a Spanish app came up in English while every
+ * page behind it was translated. Rather than make the app thread a locale through by hand,
+ * such a component resolves one itself: an explicit prop, else the provider when there is
+ * one, else the viewer's own languages.
+ *
+ * `available` is the set to match the viewer against — the locales the catalogue ships, since
+ * a component outside the provider has no document to ask.
+ */
+export declare function useStandaloneUiText(locale: string | undefined, overrides: Partial<UiMessages> | undefined): (key: UiMessageKey) => string;
 /** Substitute `:param` segments in an href with a document's values. */
 export declare function resolveHref(href: string, doc?: Doc): string;
 export interface DispatchOptions {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groveback/ui",
-  "version": "0.4.0",
+  "version": "0.7.0",
   "description": "React primitives for Groveback Studio screens — tables, forms, detail views and relation pickers that read through the Groveback SDK, so every query passes the policy engine.",
   "type": "module",
   "main": "./dist/index.js",