@umituz/web-dashboard 3.2.4 → 4.1.0

package/src/domains/settings/hooks/useSettings.ts

@@ -1,75 +1,100 @@
 /**
  * Settings Hooks
  *
- * Custom React hooks for settings functionality
+ * Custom React hooks for settings functionality.
+ * Uses a single `useReducer` so the three update paths share one
+ * well-tested tree-walking helper instead of duplicating it.
  */
 
-import { useState, useCallback } from "react";
+import { useReducer, useCallback } from "react";
 import type { SettingsConfig, SettingsItem } from "../types/settings";
 
+/**
+ * Action discriminated union for the settings reducer.
+ */
+type SettingsAction =
+  | { type: 'updateItem'; sectionKey: string; itemKey: string; updates: Partial<SettingsItem> }
+  | { type: 'toggleItem'; sectionKey: string; itemKey: string }
+  | { type: 'setItemBadge'; sectionKey: string; itemKey: string; badge: number | undefined };
+
+/**
+ * Apply a transform to the item identified by (sectionKey, itemKey).
+ * Single source of truth for the tree-walking logic.
+ */
+const mapItemInTree = (
+  config: SettingsConfig,
+  sectionKey: string,
+  itemKey: string,
+  transform: (item: SettingsItem) => SettingsItem,
+): SettingsConfig => ({
+  ...config,
+  sections: config.sections.map((section) =>
+    section.key !== sectionKey
+      ? section
+      : {
+          ...section,
+          items: section.items.map((item) => (item.key === itemKey ? transform(item) : item)),
+        },
+  ),
+});
+
+const settingsReducer = (state: SettingsConfig, action: SettingsAction): SettingsConfig => {
+  switch (action.type) {
+    case 'updateItem':
+      return mapItemInTree(state, action.sectionKey, action.itemKey, (item) => ({
+        ...item,
+        ...action.updates,
+      }));
+    case 'toggleItem':
+      return mapItemInTree(state, action.sectionKey, action.itemKey, (item) => ({
+        ...item,
+        // Tri-state semantics: undefined is treated as enabled by default.
+        enabled: item.enabled === undefined ? false : !item.enabled,
+      }));
+    case 'setItemBadge':
+      return mapItemInTree(state, action.sectionKey, action.itemKey, (item) => ({
+        ...item,
+        badge: action.badge,
+      }));
+  }
+};
+
+/**
+ * Public surface of the hook. Returned callbacks are stable
+ * (no deps that change between renders).
+ */
+export interface UseSettingsReturn {
+  config: SettingsConfig;
+  updateItem: (sectionKey: string, itemKey: string, updates: Partial<SettingsItem>) => void;
+  toggleItem: (sectionKey: string, itemKey: string) => void;
+  setItemBadge: (sectionKey: string, itemKey: string, badge: number | undefined) => void;
+}
+
 /**
  * Use Settings Hook
  *
- * Manages settings state and actions
- *
- * @param initialConfig - Initial settings configuration
- * @returns Settings state and actions
+ * Manages settings configuration state and provides update actions.
  */
-export function useSettings(initialConfig: SettingsConfig) {
-  const [config, setConfig] = useState<SettingsConfig>(initialConfig);
+export function useSettings(initialConfig: SettingsConfig): UseSettingsReturn {
+  const [config, dispatch] = useReducer(settingsReducer, initialConfig);
 
   const updateItem = useCallback(
     (sectionKey: string, itemKey: string, updates: Partial<SettingsItem>) => {
-      setConfig((prev) => ({
-        ...prev,
-        sections: prev.sections.map((section) =>
-          section.key === sectionKey
-            ? {
-                ...section,
-                items: section.items.map((item) =>
-                  item.key === itemKey ? { ...item, ...updates } : item
-                ),
-              }
-            : section
-        ),
-      }));
+      dispatch({ type: 'updateItem', sectionKey, itemKey, updates });
     },
-    []
+    [],
   );
 
   const toggleItem = useCallback((sectionKey: string, itemKey: string) => {
-    setConfig((prev) => ({
-      ...prev,
-      sections: prev.sections.map((section) =>
-        section.key === sectionKey
-          ? {
-              ...section,
-              items: section.items.map((item) =>
-                item.key === itemKey
-                  ? { ...item, enabled: item.enabled === undefined ? true : !item.enabled }
-                  : item
-              ),
-            }
-          : section
-      ),
-    }));
+    dispatch({ type: 'toggleItem', sectionKey, itemKey });
   }, []);
 
-  const setItemBadge = useCallback((sectionKey: string, itemKey: string, badge: number | undefined) => {
-    setConfig((prev) => ({
-      ...prev,
-      sections: prev.sections.map((section) =>
-        section.key === sectionKey
-          ? {
-              ...section,
-              items: section.items.map((item) =>
-                item.key === itemKey ? { ...item, badge } : item
-              ),
-            }
-          : section
-      ),
-    }));
-  }, []);
+  const setItemBadge = useCallback(
+    (sectionKey: string, itemKey: string, badge: number | undefined) => {
+      dispatch({ type: 'setItemBadge', sectionKey, itemKey, badge });
+    },
+    [],
+  );
 
   return {
     config,

package/src/domains/settings/types/settings.ts

@@ -20,6 +20,8 @@ export interface SettingsItem {
   icon?: LucideIcon;
   /** Route path for this setting */
   path?: string;
+  /** Click handler when no route is available */
+  onClick?: () => void;
   /** Whether this item is enabled */
   enabled?: boolean;
   /** Required permission to access */

package/src/domains/settings/utils/i18nKeys.ts

@@ -0,0 +1,18 @@
+/**
+ * Settings domain i18n keys (admin skeleton screens) — the
+ * documented string contract. Column titles and role labels come
+ * from props; only empty/denied states fall back to these keys.
+ */
+
+export const SETTINGS_ADMIN_KEYS = {
+  users: {
+    empty: "settings.users.empty",
+  },
+  matrix: {
+    granted: "settings.matrix.granted",
+    denied: "settings.matrix.denied",
+  },
+  audit: {
+    empty: "settings.audit.empty",
+  },
+} as const;

package/src/domains/settings/utils/index.ts

@@ -9,3 +9,4 @@ export {
   getSettingsDefaultRoute,
   generateSettingsKey,
 } from './settings';
+export { SETTINGS_ADMIN_KEYS } from './i18nKeys';

package/src/domains/settings/utils/settings.ts

@@ -51,13 +51,20 @@ export function filterSettingsByPermission<T extends SettingsItem>(
   });
 }
 
+/**
+ * Fallback route when no default or first available route can be resolved.
+ * Caller should treat this as an explicit "no route configured" signal
+ * rather than a silent success.
+ */
+export const SETTINGS_FALLBACK_ROUTE = "/settings";
+
 /**
  * Get default route from settings config
  *
- * @param config - Settings configuration
- * @returns Default route or first available route
+ * Returns null when no default route is resolvable. The caller is
+ * responsible for handling that case (e.g. redirect, error).
  */
-export function getSettingsDefaultRoute(config: SettingsConfig): string {
+export function getSettingsDefaultRoute(config: SettingsConfig): string | null {
   if (config.defaultRoute) return config.defaultRoute;
 
   for (const section of config.sections) {
@@ -65,7 +72,7 @@ export function getSettingsDefaultRoute(config: SettingsConfig): string {
     if (firstEnabled?.path) return firstEnabled.path;
   }
 
-  return "/settings";
+  return null;
 }
 
 /**

package/src/i18n/I18nContext.tsx

@@ -0,0 +1,33 @@
+/**
+ * Dashboard i18n injection.
+ *
+ * The package ships no i18n runtime. Hosts that have one wrap their
+ * app once: `<DashboardI18nProvider t={i18n.t}>` — the signature
+ * already matches i18next (and the fleet's custom `t()` helpers).
+ * Without a provider, `useT()` falls back to `defaultT`, which
+ * humanizes catalog keys into readable English.
+ *
+ * Components consume only `useT()`; the key catalogs (i18nKeys.ts)
+ * remain the documented string contract.
+ */
+
+import { createContext, useContext, type ReactNode } from "react";
+import { defaultT } from "./defaultT";
+import type { TranslateFn } from "./types";
+
+export interface DashboardI18nProviderProps {
+  /** Host translation function (e.g. i18next's `t`). */
+  t: TranslateFn;
+  children: ReactNode;
+}
+
+const I18nContext = createContext<TranslateFn | null>(null);
+
+export const DashboardI18nProvider = ({
+  t,
+  children,
+}: DashboardI18nProviderProps) => (
+  <I18nContext.Provider value={t}>{children}</I18nContext.Provider>
+);
+
+export const useT = (): TranslateFn => useContext(I18nContext) ?? defaultT;

package/src/i18n/defaultT.test.ts

@@ -0,0 +1,43 @@
+import { describe, expect, it } from "vitest";
+import { defaultT } from "./defaultT";
+
+describe("defaultT", () => {
+  it("humanizes the last key segment", () => {
+    expect(defaultT("auth.login.welcomeBack")).toBe("Welcome back");
+  });
+
+  it("splits camelCase into words", () => {
+    expect(defaultT("auth.passwordStrength.passwordsDoNotMatch")).toBe(
+      "Passwords do not match",
+    );
+  });
+
+  it("splits snake_case and kebab-case segments", () => {
+    expect(defaultT("common.error_code")).toBe("Error code");
+    expect(defaultT("common.error-code")).toBe("Error code");
+  });
+
+  it("keeps digits attached to their word", () => {
+    expect(defaultT("analytics.common.last7Days")).toBe("Last7 days");
+  });
+
+  it("interpolates {{param}} placeholders the text carries", () => {
+    expect(defaultT("custom.{{brand}} console", { brand: "Acme" })).toBe(
+      "Acme console",
+    );
+  });
+
+  it("ignores params the humanized text cannot place", () => {
+    expect(defaultT("auth.login.signInTo", { brand: "Acme" })).toBe(
+      "Sign in to",
+    );
+  });
+
+  it("returns the raw key when it has no segments", () => {
+    expect(defaultT("")).toBe("");
+  });
+
+  it("handles single-segment keys", () => {
+    expect(defaultT("settings")).toBe("Settings");
+  });
+});

package/src/i18n/defaultT.ts

@@ -0,0 +1,34 @@
+/**
+ * Default translator — the zero-config fallback when no host i18n
+ * is provided. Humanizes catalog keys into sentence case
+ * ("auth.login.welcomeBack" → "Welcome back") and interpolates
+ * `{{param}}` placeholders when the humanized text carries one.
+ * Params the text cannot place are ignored — real interpolation is
+ * the host runtime's job via the DashboardI18nProvider bridge.
+ */
+
+import type { TranslateFn } from "./types";
+
+/** Split a key segment into words: camelCase, snake_case, kebab-case. */
+const WORD_SPLIT = /[._\-]+|(?<=[a-z0-9])(?=[A-Z])/g;
+
+const humanizeSegment = (segment: string): string => {
+  const words = segment.split(WORD_SPLIT).filter(Boolean);
+  if (words.length === 0) return segment;
+  const sentence = words.join(" ").toLowerCase();
+  return sentence.charAt(0).toUpperCase() + sentence.slice(1);
+};
+
+/** Replace `{{param}}` placeholders with param values. */
+const interpolate = (text: string, params?: Record<string, unknown>): string => {
+  if (!params) return text;
+  return text.replace(/\{\{\s*(\w+)\s*\}\}/g, (match, name: string) =>
+    name in params ? String(params[name]) : match,
+  );
+};
+
+export const defaultT: TranslateFn = (key, params) => {
+  const segments = key.split(".").filter(Boolean);
+  const source = segments.length > 0 ? segments[segments.length - 1] : key;
+  return interpolate(humanizeSegment(source), params);
+};

package/src/i18n/index.ts

@@ -0,0 +1,7 @@
+export {
+  DashboardI18nProvider,
+  useT,
+  type DashboardI18nProviderProps,
+} from "./I18nContext";
+export { defaultT } from "./defaultT";
+export type { TranslateFn } from "./types";

package/src/i18n/types.ts

@@ -0,0 +1,13 @@
+/**
+ * Translation function contract.
+ *
+ * Keyed by the package's i18n catalog constants (e.g. AUTH_KEYS);
+ * `params` feeds `{{placeholder}}` interpolation. The signature is
+ * deliberately compatible with i18next's `t` so hosts can bridge
+ * their own setup: `<DashboardI18nProvider t={i18n.t}>`.
+ */
+
+export type TranslateFn = (
+  key: string,
+  params?: Record<string, unknown>,
+) => string;

package/src/index.ts

@@ -7,15 +7,9 @@
  * @version 3.0.0
  */
 
-// Export all domains
+// Core domains with complete public API
 export * from './domains/layouts';
 export * from './domains/settings';
-export * from './domains/billing';
-
-// Domains - using selective exports to avoid conflicts
-export * from './domains/layouts';
-export * from './domains/settings';
-export * from './domains/billing';
 export * from './domains/calendar';
 export {
   OnboardingWizard,

package/src/primitives/Button.tsx

@@ -0,0 +1,24 @@
+/**
+ * Button — delegates to the design system.
+ * Dashboard surface: variants default/destructive/outline/ghost,
+ * sizes default/sm/icon. Call-site API unchanged.
+ */
+
+import { forwardRef } from 'react';
+import { Button as DSButton } from '@umituz/web-design-system/atoms';
+
+export type ButtonVariant = 'default' | 'destructive' | 'outline' | 'ghost';
+export type ButtonSize = 'default' | 'sm' | 'icon';
+
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+}
+
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ variant = 'default', size = 'default', ...props }, ref) => (
+    <DSButton ref={ref} variant={variant} size={size} {...props} />
+  ),
+);
+
+Button.displayName = 'Button';

package/src/primitives/Checkbox.tsx

@@ -0,0 +1,17 @@
+/**
+ * Checkbox — delegates to the design system (native + onCheckedChange).
+ */
+
+import { forwardRef } from 'react';
+import { Checkbox as DSCheckbox } from '@umituz/web-design-system/atoms';
+
+export interface CheckboxProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size'> {
+  checked?: boolean;
+  onCheckedChange?: (checked: boolean) => void;
+}
+
+export const Checkbox = forwardRef<HTMLInputElement, CheckboxProps>((props, ref) => (
+  <DSCheckbox ref={ref} {...props} />
+));
+
+Checkbox.displayName = 'Checkbox';

package/src/primitives/Input.tsx

@@ -0,0 +1,23 @@
+/**
+ * Input — delegates to the design system.
+ * Native `size` (character width) has no DS counterpart; it maps to a
+ * `ch`-based width so the original prop API keeps working.
+ */
+
+import { forwardRef } from 'react';
+import { Input as DSInput } from '@umituz/web-design-system/atoms';
+
+export type InputProps = React.InputHTMLAttributes<HTMLInputElement>;
+
+export const Input = forwardRef<HTMLInputElement, InputProps>(
+  ({ type = 'text', size: nativeSize, style, ...props }, ref) => (
+    <DSInput
+      ref={ref}
+      type={type}
+      {...props}
+      style={nativeSize != null ? { width: `${nativeSize}ch`, ...style } : style}
+    />
+  ),
+);
+
+Input.displayName = 'Input';

package/src/primitives/Skeleton.tsx

@@ -0,0 +1,6 @@
+/**
+ * Skeleton — re-exported from the design system (variant API identical).
+ */
+
+export { Skeleton } from '@umituz/web-design-system/atoms';
+export type { SkeletonProps } from '@umituz/web-design-system/atoms';

package/src/primitives/cn.ts

@@ -0,0 +1,10 @@
+/**
+ * cn — conditional className join, delegated to the design system.
+ *
+ * The design system's `cn` (clsx + tailwind-merge) understands both the
+ * `udb-*` vocabulary (unknown classes pass through untouched) and real
+ * Tailwind utilities a host may pass, resolving conflicts by last-wins.
+ */
+
+export { cn } from '@umituz/web-design-system/utils/cn';
+export type { ClassValue } from '@umituz/web-design-system/utils/cn';

package/src/primitives/index.ts

@@ -0,0 +1,23 @@
+/**
+ * Local primitives — the package's only UI atoms.
+ *
+ * Replaces the `@umituz/web-design-system` dependency (v3) with a
+ * camp-agnostic set: `udb-*` classes + `--u-*` tokens, no utility
+ * framework, no cva, no radix. Import as `@umituz/web-dashboard/primitives`
+ * or relatively from inside the package.
+ */
+
+export { cn } from './cn';
+export type { ClassValue } from './cn';
+
+export { Button } from './Button';
+export type { ButtonProps, ButtonVariant, ButtonSize } from './Button';
+
+export { Input } from './Input';
+export type { InputProps } from './Input';
+
+export { Checkbox } from './Checkbox';
+export type { CheckboxProps } from './Checkbox';
+
+export { Skeleton } from './Skeleton';
+export type { SkeletonProps } from './Skeleton';