@majapisoftwares/ui 6.1.2 → 6.2.0

package/docs/STANDARDS.md

@@ -1,5 +1,7 @@
 # Padrão v1 de código e UI/UX
 
+`LoginForm` aceita `mode="providers"` com `alternative` obrigatório para autenticação exclusiva por OAuth/SSO, sem campos de senha nem callback de credenciais. O modo padrão continua `credentials`. Catálogo e starter demonstram em `/login/provider`. A identidade autenticada usa `UserMenu` no slot `footer` do `AppShell`; tema, idioma e saída permanecem no padrão compartilhado.
+
 Base atual: shadcn base-luma com @base-ui/react. Os componentes interativos expõem fronteiras use client para uso no Next.js App Router. A migração da API Radix está documentada em MIGRATION-0.2.md.
 
 ## Arquitetura e código

package/docs/validation/preference-titles.md

@@ -1,22 +1,22 @@
-# Saved-language titles
-
-The initial preference state matched server HTML in English. Child title effects
-ran before browser preferences were loaded, briefly writing the English title.
-The pre-paint visibility mask also expired after two seconds, independently of
-whether hydration had completed.
-
-`Preferences` now exposes internal readiness to `useDocumentTitle`. Titles are
-written only after the stored/browser language is resolved. The pre-paint mask
-is removed only when React has committed that language. The public API remains
-compatible, including `useDocumentTitle` outside Preferences.
-
-The catalog and generated starter consume the shared implementation. Cloud and
-the starter pin the corrected public Git source archive by its full commit SHA;
-no registry authentication or mutable dependency ref is required.
-
-Validation: Portuguese and English hydration tests record every document-title
-write and verify that all writes use the selected language. Library typecheck,
-lint, standards and build pass. Generated-starter lint, typecheck, UI standards
-and build pass. Local Chrome refresh shows `Padrões · Majapi UI` and
-`Repositórios · Majapi Cloud`, with visible Portuguese content and the button
-`Conectar repositórios`. No production deployment was performed.
+# Saved-language titles
+
+The initial preference state matched server HTML in English. Child title effects
+ran before browser preferences were loaded, briefly writing the English title.
+The pre-paint visibility mask also expired after two seconds, independently of
+whether hydration had completed.
+
+`Preferences` now exposes internal readiness to `useDocumentTitle`. Titles are
+written only after the stored/browser language is resolved. The pre-paint mask
+is removed only when React has committed that language. The public API remains
+compatible, including `useDocumentTitle` outside Preferences.
+
+The catalog and generated starter consume the shared implementation. Cloud and
+the starter pin the corrected public Git source archive by its full commit SHA;
+no registry authentication or mutable dependency ref is required.
+
+Validation: Portuguese and English hydration tests record every document-title
+write and verify that all writes use the selected language. Library typecheck,
+lint, standards and build pass. Generated-starter lint, typecheck, UI standards
+and build pass. Local Chrome refresh shows `Padrões · Majapi UI` and
+`Repositórios · Majapi Cloud`, with visible Portuguese content and the button
+`Conectar repositórios`. No production deployment was performed.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@majapisoftwares/ui",
-  "version": "6.1.2",
+  "version": "6.2.0",
   "description": "Shared Majapi UI and UX standards based on shadcn/ui",
   "publishConfig": {
     "access": "public"

package/src/components/ui/sidebar.tsx

@@ -84,8 +84,13 @@ const clampWidth = (width: number) =>
  * Applies the saved sidebar state to the server-rendered markup before the
  * browser paints (static pages can't read the cookie on the server).
  */
+const subscribeNoop = () => () => {};
+
 function SidebarRestoreScript() {
+  // Only SSR and hydration emit the script; React warns about client-created scripts, which never run.
+  const hydrating = React.useSyncExternalStore(subscribeNoop, () => false, () => true);
   const script = `(function(){try{var m=document.cookie.match(/(?:^|; )${SIDEBAR_COOKIE_NAME}=([^;]*)/);if(!m)return;var p=m[1].split(":"),mode=p[0],w=Number(p[1]),wrap=document.currentScript.parentElement;if(w)wrap.setAttribute("style",(wrap.getAttribute("style")||"").replace(/--sidebar-width:[^;]*/,"--sidebar-width:"+Math.round(Math.min(${SIDEBAR_WIDTH_MAX},Math.max(${SIDEBAR_WIDTH_MIN},w)))+"px"));var sb=wrap.querySelector('[data-slot="sidebar"]');var r=wrap.querySelector('[data-slot="sidebar-rail"]');if(r)r.setAttribute("aria-valuenow",String(mode==="compact"?48:mode==="closed"?0:Math.round(Math.min(${SIDEBAR_WIDTH_MAX},Math.max(${SIDEBAR_WIDTH_MIN},w||${SIDEBAR_WIDTH})))));if(sb&&(mode==="compact"||mode==="closed")){sb.setAttribute("data-state","collapsed");sb.setAttribute("data-collapsible",mode==="closed"?"offcanvas":"icon")}}catch(e){}})()`;
+  if (!hydrating) return null;
   return (
     <script
       suppressHydrationWarning

package/src/patterns/preferences.tsx

@@ -1,180 +1,180 @@
-"use client";
-
-import {
-  createContext,
-  useContext,
-  useEffect,
-  useState,
-  type ReactNode,
-} from "react";
-import { LanguagesIcon, MoonIcon, SunIcon } from "lucide-react";
-import {
-  LocaleProvider,
-  locales,
-  matchLocale,
-  useUiMessages,
-  type Locale,
-} from "../lib/i18n";
-import { Button } from "../components/ui/button";
-import { Toaster } from "../components/ui/sonner";
-import {
-  DropdownMenu,
-  DropdownMenuContent,
-  DropdownMenuRadioGroup,
-  DropdownMenuRadioItem,
-  DropdownMenuTrigger,
-} from "../components/ui/dropdown-menu";
-
-type Theme = "light" | "dark";
-const PreferencesContext = createContext<{
-  locale: Locale;
-  setLocale: (locale: Locale) => void;
-  theme: Theme;
-  setTheme: (theme: Theme) => void;
-} | null>(null);
-const PreferencesReadyContext = createContext(true);
-
-function read(key: string) {
-  try {
-    return localStorage.getItem(key);
-  } catch {
-    return null;
-  }
-}
-function write(key: string, value: string) {
-  try {
-    localStorage.setItem(key, value);
-  } catch {
-    // Storage can be unavailable (private mode); preferences just won't persist.
-  }
-}
-
-/**
- * Mirrors matchLocale; keep both in sync.
- * Inline this in `<head>` (e.g. `<script dangerouslySetInnerHTML>`) so the
- * stored theme applies before paint.
- */
-export const preferencesScript = `try{var d=document.documentElement;if(localStorage.getItem("theme")==="dark")d.classList.add("dark");var l=localStorage.getItem("locale");if(l!=="en"&&l!=="pt-BR"){l="en";var a=navigator.languages||[];for(var i=0;i<a.length;i++){if(/^pt/i.test(a[i])){l="pt-BR";break}if(/^en/i.test(a[i]))break}}if(l!==d.lang){d.lang=l;d.setAttribute("data-locale-pending",l)}}catch(e){}`;
-
-/**
- * Locale + theme for the whole app. Renders `defaultLocale` first (matches
- * static/server HTML), then applies the stored or browser locale on mount.
- */
-export function Preferences({
-  defaultLocale = "en",
-  children,
-}: {
-  defaultLocale?: Locale;
-  children: ReactNode;
-}) {
-  const [locale, setLocale] = useState<Locale>(defaultLocale);
-  const [theme, setTheme] = useState<Theme>("light");
-  const [ready, setReady] = useState(false);
-  useEffect(() => {
-    const stored = read("locale");
-    // eslint-disable-next-line react-hooks/set-state-in-effect -- sync from browser-only storage after hydration
-    setLocale(
-      locales.includes(stored as Locale)
-        ? (stored as Locale)
-        : matchLocale(navigator.languages),
-    );
-    setTheme(read("theme") === "dark" ? "dark" : "light");
-    setReady(true);
-  }, []);
-  useEffect(() => {
-    if (!ready) return;
-    const root = document.documentElement;
-    root.lang = locale;
-    // The pre-paint script hides the page until the saved locale is rendered.
-    if (root.dataset.localePending === locale)
-      delete root.dataset.localePending;
-  }, [locale, ready]);
-  useEffect(() => {
-    document.documentElement.classList.toggle("dark", theme === "dark");
-  }, [theme]);
-  return (
-    <PreferencesContext.Provider
-      value={{
-        locale,
-        setLocale: (next) => {
-          setLocale(next);
-          write("locale", next);
-        },
-        theme,
-        setTheme: (next) => {
-          setTheme(next);
-          write("theme", next);
-        },
-      }}
-    >
-      <PreferencesReadyContext.Provider value={ready}>
-        <LocaleProvider locale={locale}>
-          {children}
-          <Toaster theme={theme} />
-        </LocaleProvider>
-      </PreferencesReadyContext.Provider>
-    </PreferencesContext.Provider>
-  );
-}
-
-/**
- * Owns `document.title` so it follows the active language. Leave `title` out
- * of Next.js metadata, or Next will overwrite it after hydration.
- */
-export function useDocumentTitle(title: string) {
-  const ready = useContext(PreferencesReadyContext);
-  useEffect(() => {
-    if (!ready) return;
-    document.title = title;
-  }, [title, ready]);
-}
-
-export function usePreferences() {
-  const context = useContext(PreferencesContext);
-  if (!context)
-    throw new Error("usePreferences must be used within Preferences.");
-  return context;
-}
-
-const localeNames: Record<Locale, string> = {
-  en: "English",
-  "pt-BR": "Português",
-};
-
-/** Language menu and theme toggle, e.g. for `AppShell` actions. */
-export function PreferenceControls() {
-  const { locale, setLocale, theme, setTheme } = usePreferences();
-  const t = useUiMessages();
-  return (
-    <>
-      <DropdownMenu>
-        <DropdownMenuTrigger
-          render={<Button variant="ghost" size="sm" aria-label={t.language} />}
-        >
-          <LanguagesIcon />
-          {locale === "en" ? "EN" : "PT"}
-        </DropdownMenuTrigger>
-        <DropdownMenuContent align="end">
-          <DropdownMenuRadioGroup
-            value={locale}
-            onValueChange={(value) => setLocale(value as Locale)}
-          >
-            {locales.map((value) => (
-              <DropdownMenuRadioItem key={value} value={value}>
-                {localeNames[value]}
-              </DropdownMenuRadioItem>
-            ))}
-          </DropdownMenuRadioGroup>
-        </DropdownMenuContent>
-      </DropdownMenu>
-      <Button
-        variant="ghost"
-        size="icon-sm"
-        aria-label={t.toggleTheme}
-        onClick={() => setTheme(theme === "dark" ? "light" : "dark")}
-      >
-        {theme === "dark" ? <SunIcon /> : <MoonIcon />}
-      </Button>
-    </>
-  );
-}
+"use client";
+
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useState,
+  type ReactNode,
+} from "react";
+import { LanguagesIcon, MoonIcon, SunIcon } from "lucide-react";
+import {
+  LocaleProvider,
+  locales,
+  matchLocale,
+  useUiMessages,
+  type Locale,
+} from "../lib/i18n";
+import { Button } from "../components/ui/button";
+import { Toaster } from "../components/ui/sonner";
+import {
+  DropdownMenu,
+  DropdownMenuContent,
+  DropdownMenuRadioGroup,
+  DropdownMenuRadioItem,
+  DropdownMenuTrigger,
+} from "../components/ui/dropdown-menu";
+
+type Theme = "light" | "dark";
+const PreferencesContext = createContext<{
+  locale: Locale;
+  setLocale: (locale: Locale) => void;
+  theme: Theme;
+  setTheme: (theme: Theme) => void;
+} | null>(null);
+const PreferencesReadyContext = createContext(true);
+
+function read(key: string) {
+  try {
+    return localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+function write(key: string, value: string) {
+  try {
+    localStorage.setItem(key, value);
+  } catch {
+    // Storage can be unavailable (private mode); preferences just won't persist.
+  }
+}
+
+/**
+ * Mirrors matchLocale; keep both in sync.
+ * Inline this in `<head>` (e.g. `<script dangerouslySetInnerHTML>`) so the
+ * stored theme applies before paint.
+ */
+export const preferencesScript = `try{var d=document.documentElement;if(localStorage.getItem("theme")==="dark")d.classList.add("dark");var l=localStorage.getItem("locale");if(l!=="en"&&l!=="pt-BR"){l="en";var a=navigator.languages||[];for(var i=0;i<a.length;i++){if(/^pt/i.test(a[i])){l="pt-BR";break}if(/^en/i.test(a[i]))break}}if(l!==d.lang){d.lang=l;d.setAttribute("data-locale-pending",l)}}catch(e){}`;
+
+/**
+ * Locale + theme for the whole app. Renders `defaultLocale` first (matches
+ * static/server HTML), then applies the stored or browser locale on mount.
+ */
+export function Preferences({
+  defaultLocale = "en",
+  children,
+}: {
+  defaultLocale?: Locale;
+  children: ReactNode;
+}) {
+  const [locale, setLocale] = useState<Locale>(defaultLocale);
+  const [theme, setTheme] = useState<Theme>("light");
+  const [ready, setReady] = useState(false);
+  useEffect(() => {
+    const stored = read("locale");
+    // eslint-disable-next-line react-hooks/set-state-in-effect -- sync from browser-only storage after hydration
+    setLocale(
+      locales.includes(stored as Locale)
+        ? (stored as Locale)
+        : matchLocale(navigator.languages),
+    );
+    setTheme(read("theme") === "dark" ? "dark" : "light");
+    setReady(true);
+  }, []);
+  useEffect(() => {
+    if (!ready) return;
+    const root = document.documentElement;
+    root.lang = locale;
+    // The pre-paint script hides the page until the saved locale is rendered.
+    if (root.dataset.localePending === locale)
+      delete root.dataset.localePending;
+  }, [locale, ready]);
+  useEffect(() => {
+    document.documentElement.classList.toggle("dark", theme === "dark");
+  }, [theme]);
+  return (
+    <PreferencesContext.Provider
+      value={{
+        locale,
+        setLocale: (next) => {
+          setLocale(next);
+          write("locale", next);
+        },
+        theme,
+        setTheme: (next) => {
+          setTheme(next);
+          write("theme", next);
+        },
+      }}
+    >
+      <PreferencesReadyContext.Provider value={ready}>
+        <LocaleProvider locale={locale}>
+          {children}
+          <Toaster theme={theme} />
+        </LocaleProvider>
+      </PreferencesReadyContext.Provider>
+    </PreferencesContext.Provider>
+  );
+}
+
+/**
+ * Owns `document.title` so it follows the active language. Leave `title` out
+ * of Next.js metadata, or Next will overwrite it after hydration.
+ */
+export function useDocumentTitle(title: string) {
+  const ready = useContext(PreferencesReadyContext);
+  useEffect(() => {
+    if (!ready) return;
+    document.title = title;
+  }, [title, ready]);
+}
+
+export function usePreferences() {
+  const context = useContext(PreferencesContext);
+  if (!context)
+    throw new Error("usePreferences must be used within Preferences.");
+  return context;
+}
+
+const localeNames: Record<Locale, string> = {
+  en: "English",
+  "pt-BR": "Português",
+};
+
+/** Language menu and theme toggle, e.g. for `AppShell` actions. */
+export function PreferenceControls() {
+  const { locale, setLocale, theme, setTheme } = usePreferences();
+  const t = useUiMessages();
+  return (
+    <>
+      <DropdownMenu>
+        <DropdownMenuTrigger
+          render={<Button variant="ghost" size="sm" aria-label={t.language} />}
+        >
+          <LanguagesIcon />
+          {locale === "en" ? "EN" : "PT"}
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="end">
+          <DropdownMenuRadioGroup
+            value={locale}
+            onValueChange={(value) => setLocale(value as Locale)}
+          >
+            {locales.map((value) => (
+              <DropdownMenuRadioItem key={value} value={value}>
+                {localeNames[value]}
+              </DropdownMenuRadioItem>
+            ))}
+          </DropdownMenuRadioGroup>
+        </DropdownMenuContent>
+      </DropdownMenu>
+      <Button
+        variant="ghost"
+        size="icon-sm"
+        aria-label={t.toggleTheme}
+        onClick={() => setTheme(theme === "dark" ? "light" : "dark")}
+      >
+        {theme === "dark" ? <SunIcon /> : <MoonIcon />}
+      </Button>
+    </>
+  );
+}

package/src/templates/login-form.tsx

@@ -1,129 +1,140 @@
-"use client";
-
-import { useId, type ReactNode } from "react";
-import { Button } from "../components/ui/button";
-import { Input } from "../components/ui/input";
-import { Field, FieldGroup, FieldLabel } from "../components/ui/field";
-import { Alert, AlertDescription } from "../components/ui/alert";
-import {
-  Card,
-  CardContent,
-  CardDescription,
-  CardHeader,
-  CardTitle,
-} from "../components/ui/card";
-import { defineMessages, useMessages } from "../lib/i18n";
-
-const messages = defineMessages({
-  en: {
-    title: "Welcome back",
-    email: "Email",
-    password: "Password",
-    submit: "Log in",
-    pending: "Logging in…",
-  },
-  "pt-BR": {
-    title: "Bem-vindo de volta",
-    email: "E-mail",
-    password: "Senha",
-    submit: "Entrar",
-    pending: "Entrando…",
-  },
-});
-
-export interface LoginValues {
-  email: string;
-  password: string;
-}
-export interface LoginFormProps {
-  onSubmit: (values: LoginValues) => void;
-  pending?: boolean;
-  error?: string;
-  title?: string;
-  description?: string;
-  submitLabel?: string;
-  /** Shown next to the password label, e.g. a "Forgot password?" link. */
-  recovery?: ReactNode;
-  /** Shown above the fields, e.g. OAuth buttons. */
-  alternative?: ReactNode;
-  footer?: ReactNode;
-}
-export function LoginForm({
-  onSubmit,
-  pending = false,
-  error,
-  title,
-  description,
-  submitLabel,
-  recovery,
-  alternative,
-  footer,
-}: LoginFormProps) {
-  const id = useId();
-  const t = useMessages(messages);
-  return (
-    <Card>
-      <CardHeader className="text-center">
-        <CardTitle className="text-xl">{title ?? t.title}</CardTitle>
-        {description ? <CardDescription>{description}</CardDescription> : null}
-      </CardHeader>
-      <CardContent>
-        <form
-          aria-busy={pending}
-          onSubmit={(event) => {
-            event.preventDefault();
-            const data = new FormData(event.currentTarget);
-            onSubmit({
-              email: String(data.get("email") ?? ""),
-              password: String(data.get("password") ?? ""),
-            });
-          }}
-        >
-          <FieldGroup>
-            {alternative}
-            {error ? (
-              <Alert variant="destructive">
-                <AlertDescription>{error}</AlertDescription>
-              </Alert>
-            ) : null}
-            <Field>
-              <FieldLabel htmlFor={`${id}-email`}>{t.email}</FieldLabel>
-              <Input
-                id={`${id}-email`}
-                name="email"
-                type="email"
-                autoComplete="username"
-                required
-                disabled={pending}
-              />
-            </Field>
-            <Field>
-              <div className="flex items-center">
-                <FieldLabel htmlFor={`${id}-password`}>{t.password}</FieldLabel>
-                {recovery ? (
-                  <div className="ml-auto text-sm">{recovery}</div>
-                ) : null}
-              </div>
-              <Input
-                id={`${id}-password`}
-                name="password"
-                type="password"
-                autoComplete="current-password"
-                required
-                disabled={pending}
-              />
-            </Field>
-            <Button type="submit" disabled={pending}>
-              {pending ? t.pending : (submitLabel ?? t.submit)}
-            </Button>
-            {footer ? (
-              <div className="text-center text-sm text-muted-foreground">
-                {footer}
-              </div>
-            ) : null}
-          </FieldGroup>
-        </form>
-      </CardContent>
-    </Card>
-  );
-}
+"use client";
+
+import { useId, type ReactNode } from "react";
+import { Button } from "../components/ui/button";
+import { Input } from "../components/ui/input";
+import { Field, FieldGroup, FieldLabel } from "../components/ui/field";
+import { Alert, AlertDescription } from "../components/ui/alert";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "../components/ui/card";
+import { defineMessages, useMessages } from "../lib/i18n";
+
+const messages = defineMessages({
+  en: {
+    title: "Welcome back",
+    email: "Email",
+    password: "Password",
+    submit: "Log in",
+    pending: "Logging in…",
+  },
+  "pt-BR": {
+    title: "Bem-vindo de volta",
+    email: "E-mail",
+    password: "Senha",
+    submit: "Entrar",
+    pending: "Entrando…",
+  },
+});
+
+export interface LoginValues {
+  email: string;
+  password: string;
+}
+interface LoginFormOptions {
+  pending?: boolean;
+  error?: string;
+  title?: string;
+  description?: string;
+  submitLabel?: string;
+  /** Shown next to the password label, e.g. a "Forgot password?" link. */
+  recovery?: ReactNode;
+  /** Shown above the fields, e.g. OAuth buttons. */
+  alternative?: ReactNode;
+  footer?: ReactNode;
+}
+export type LoginFormProps = LoginFormOptions &
+  (
+    | { mode?: "credentials"; onSubmit: (values: LoginValues) => void }
+    | { mode: "providers"; onSubmit?: never; alternative: ReactNode }
+  );
+export function LoginForm({
+  mode = "credentials",
+  onSubmit,
+  pending = false,
+  error,
+  title,
+  description,
+  submitLabel,
+  recovery,
+  alternative,
+  footer,
+}: LoginFormProps) {
+  const id = useId();
+  const t = useMessages(messages);
+  return (
+    <Card>
+      <CardHeader className="text-center">
+        <CardTitle className="text-xl">{title ?? t.title}</CardTitle>
+        {description ? <CardDescription>{description}</CardDescription> : null}
+      </CardHeader>
+      <CardContent>
+        <form
+          aria-busy={pending}
+          onSubmit={(event) => {
+            event.preventDefault();
+            const data = new FormData(event.currentTarget);
+            onSubmit?.({
+              email: String(data.get("email") ?? ""),
+              password: String(data.get("password") ?? ""),
+            });
+          }}
+        >
+          <FieldGroup>
+            {alternative}
+            {error ? (
+              <Alert variant="destructive">
+                <AlertDescription>{error}</AlertDescription>
+              </Alert>
+            ) : null}
+            {mode === "credentials" ? (
+              <>
+                <Field>
+                  <FieldLabel htmlFor={`${id}-email`}>{t.email}</FieldLabel>
+                  <Input
+                    id={`${id}-email`}
+                    name="email"
+                    type="email"
+                    autoComplete="username"
+                    required
+                    disabled={pending}
+                  />
+                </Field>
+                <Field>
+                  <div className="flex items-center">
+                    <FieldLabel htmlFor={`${id}-password`}>
+                      {t.password}
+                    </FieldLabel>
+                    {recovery ? (
+                      <div className="ml-auto text-sm">{recovery}</div>
+                    ) : null}
+                  </div>
+                  <Input
+                    id={`${id}-password`}
+                    name="password"
+                    type="password"
+                    autoComplete="current-password"
+                    required
+                    disabled={pending}
+                  />
+                </Field>
+                <Button type="submit" disabled={pending}>
+                  {pending ? t.pending : (submitLabel ?? t.submit)}
+                </Button>
+              </>
+            ) : null}
+            {footer ? (
+              <div className="text-center text-sm text-muted-foreground">
+                {footer}
+              </div>
+            ) : null}
+          </FieldGroup>
+        </form>
+      </CardContent>
+    </Card>
+  );
+}