@umituz/web-dashboard 3.2.2 → 4.0.0

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

@@ -4,3 +4,13 @@
 
 export { SettingsLayout } from './SettingsLayout';
 export { SettingsSection } from './SettingsSection';
+export {
+  UserManagementTable,
+  type UserManagementTableProps,
+  type ManagedUser,
+} from './UserManagementTable';
+export {
+  PermissionMatrixScreen,
+  type PermissionMatrixScreenProps,
+} from './PermissionMatrixScreen';
+export { AuditLogList, type AuditLogListProps, type AuditEntry } from './AuditLogList';

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/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,30 @@
+/**
+ * Button — camp-agnostic action button (`udb-btn`).
+ *
+ * Clones only the surface this package actually uses: variants
+ * default/destructive/outline/ghost, sizes default/sm/icon. No `asChild`
+ * (radix-free), no variant library — classes come from `styles.css`.
+ */
+
+import { forwardRef, type ButtonHTMLAttributes } from 'react';
+import { cn } from './cn';
+
+export type ButtonVariant = 'default' | 'destructive' | 'outline' | 'ghost';
+export type ButtonSize = 'default' | 'sm' | 'icon';
+
+export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+}
+
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
+  ({ className, variant = 'default', size = 'default', ...props }, ref) => (
+    <button
+      ref={ref}
+      className={cn('udb-btn', `udb-btn--${variant}`, `udb-btn--${size}`, className)}
+      {...props}
+    />
+  ),
+);
+
+Button.displayName = 'Button';

package/src/primitives/Checkbox.tsx

@@ -0,0 +1,40 @@
+/**
+ * Checkbox — native checkbox with a boolean-change callback (`udb-checkbox`).
+ *
+ * Keeps the `onCheckedChange` convenience this package relies on; every
+ * other native attribute passes straight through.
+ */
+
+import { forwardRef, useCallback, type InputHTMLAttributes } from 'react';
+import { cn } from './cn';
+
+export interface CheckboxProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'size'> {
+  checked?: boolean;
+  onCheckedChange?: (checked: boolean) => void;
+}
+
+export const Checkbox = forwardRef<HTMLInputElement, CheckboxProps>(
+  ({ className, checked, onCheckedChange, onChange, ...props }, ref) => {
+    // Memoized so parent re-renders don't recreate the handler identity.
+    const handleChange = useCallback(
+      (e: React.ChangeEvent<HTMLInputElement>) => {
+        onCheckedChange?.(e.target.checked);
+        onChange?.(e);
+      },
+      [onCheckedChange, onChange],
+    );
+
+    return (
+      <input
+        ref={ref}
+        type="checkbox"
+        checked={checked}
+        onChange={handleChange}
+        className={cn('udb-checkbox', className)}
+        {...props}
+      />
+    );
+  },
+);
+
+Checkbox.displayName = 'Checkbox';

package/src/primitives/Input.tsx

@@ -0,0 +1,19 @@
+/**
+ * Input — text input field (`udb-input`).
+ *
+ * Minimal clone of the surface this package uses: a native input with
+ * token-driven styling. Everything else passes through untouched.
+ */
+
+import { forwardRef, type InputHTMLAttributes } from 'react';
+import { cn } from './cn';
+
+export type InputProps = InputHTMLAttributes<HTMLInputElement>;
+
+export const Input = forwardRef<HTMLInputElement, InputProps>(
+  ({ className, type = 'text', ...props }, ref) => (
+    <input ref={ref} type={type} className={cn('udb-input', className)} {...props} />
+  ),
+);
+
+Input.displayName = 'Input';

package/src/primitives/Skeleton.tsx

@@ -0,0 +1,26 @@
+/**
+ * Skeleton — loading placeholder (`udb-skeleton`).
+ *
+ * The pulse animation is defined in `styles.css` (a CSS file can ship
+ * keyframes; inline styles cannot).
+ */
+
+import { forwardRef, type HTMLAttributes } from 'react';
+import { cn } from './cn';
+
+export interface SkeletonProps extends HTMLAttributes<HTMLDivElement> {
+  variant?: 'text' | 'circular' | 'rectangular';
+}
+
+export const Skeleton = forwardRef<HTMLDivElement, SkeletonProps>(
+  ({ className, variant = 'rectangular', ...props }, ref) => (
+    <div
+      ref={ref}
+      className={cn('udb-skeleton', `udb-skeleton--${variant}`, className)}
+      role="status"
+      {...props}
+    />
+  ),
+);
+
+Skeleton.displayName = 'Skeleton';

package/src/primitives/cn.ts

@@ -0,0 +1,15 @@
+/**
+ * cn — conditional className join (clsx only).
+ *
+ * Deliberately drops the old tailwind-merge layer: v4 ships its own
+ * `udb-*` class vocabulary where overrides append instead of conflicting,
+ * so plain conditional joining is the whole job.
+ */
+
+import { clsx, type ClassValue } from 'clsx';
+
+export type { ClassValue };
+
+export function cn(...inputs: ClassValue[]): string {
+  return clsx(inputs);
+}

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';