@almadar/ui 5.0.0 → 5.1.0

package/dist/docs/index.d.cts

@@ -194,12 +194,15 @@ declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAtt
 /**
  * Icon Atom Component
  *
- * A wrapper component for Lucide icons with consistent sizing and styling.
- * Uses theme-aware CSS variables for stroke width and color.
+ * Renders an icon from the active icon family (Layer 1 Iconography axis —
+ * see lib/iconFamily.ts). Canonical names are lucide kebab-case; the resolver
+ * dispatches to phosphor / tabler / fa-solid when `--icon-family` selects them,
+ * re-rendering automatically on theme switch.
  *
  * Supports two APIs:
- * - `icon` prop: Pass a LucideIcon component directly
- * - `name` prop: Pass a string icon name (resolved from iconMap)
+ * - `icon` prop: Pass a LucideIcon component directly (bypasses family resolver
+ *   — used for direct lucide component refs, stays in lucide regardless of theme)
+ * - `name` prop: Pass a canonical kebab-case name (family-aware, swaps on theme)
  */
 
 type IconSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';

package/dist/docs/index.js

@@ -1,8 +1,11 @@
-import React5, { createContext, useCallback, useContext, useMemo, useState, useRef, useEffect } from 'react';
+import React7, { createContext, useCallback, useContext, useMemo, useSyncExternalStore, useState, useRef, useEffect } from 'react';
 import { createLogger } from '@almadar/logger';
 import { jsxs, jsx } from 'react/jsx-runtime';
 import * as LucideIcons from 'lucide-react';
-import { Loader2, ChevronDown, X } from 'lucide-react';
+import { Loader2 } from 'lucide-react';
+import * as PhosphorIcons from '@phosphor-icons/react';
+import * as TablerIcons from '@tabler/icons-react';
+import * as FaIcons from 'react-icons/fa';
 
 // node_modules/clsx/dist/clsx.mjs
 function r(e) {
@@ -2705,7 +2708,7 @@ var positionStyles = {
   fixed: "fixed",
   sticky: "sticky"
 };
-var Box = React5.forwardRef(
+var Box = React7.forwardRef(
   ({
     padding,
     paddingX,
@@ -2755,7 +2758,7 @@ var Box = React5.forwardRef(
       onMouseLeave?.(e);
     }, [hoverEvent, eventBus, onMouseLeave]);
     const isClickable = action || onClick;
-    return React5.createElement(
+    return React7.createElement(
       Component,
       {
         ref,
@@ -2974,41 +2977,366 @@ var Typography = ({
   );
 };
 Typography.displayName = "Typography";
-var iconAliases = {
-  "close": LucideIcons.X,
-  "trash": LucideIcons.Trash2,
-  "loader": LucideIcons.Loader2,
-  "stop": LucideIcons.Square,
-  "volume": LucideIcons.Volume2,
-  "volume-off": LucideIcons.VolumeX,
-  "refresh": LucideIcons.RefreshCw,
-  "share": LucideIcons.Share2,
-  "sort-asc": LucideIcons.ArrowUpNarrowWide,
-  "sort-desc": LucideIcons.ArrowDownNarrowWide
-};
+var DEFAULT_FAMILY = "lucide";
+var VALID_FAMILIES = [
+  "lucide",
+  "phosphor-outline",
+  "phosphor-fill",
+  "phosphor-duotone",
+  "tabler",
+  "fa-solid"
+];
+function getCurrentIconFamily() {
+  if (typeof window === "undefined" || typeof document === "undefined") {
+    return DEFAULT_FAMILY;
+  }
+  const raw = getComputedStyle(document.documentElement).getPropertyValue("--icon-family").trim().replace(/^["']|["']$/g, "");
+  return VALID_FAMILIES.includes(raw) ? raw : DEFAULT_FAMILY;
+}
+var cachedFamily = null;
+var listeners = /* @__PURE__ */ new Set();
+var observer = null;
+function ensureObserver() {
+  if (typeof window === "undefined" || observer) return;
+  observer = new MutationObserver(() => {
+    const next = getCurrentIconFamily();
+    if (next !== cachedFamily) {
+      cachedFamily = next;
+      listeners.forEach((fn) => fn());
+    }
+  });
+  observer.observe(document.documentElement, {
+    attributes: true,
+    attributeFilter: ["data-theme", "style"]
+  });
+  cachedFamily = getCurrentIconFamily();
+}
+function subscribeIconFamily(notify) {
+  ensureObserver();
+  listeners.add(notify);
+  return () => {
+    listeners.delete(notify);
+  };
+}
+function getIconFamilySnapshot() {
+  if (cachedFamily !== null) return cachedFamily;
+  cachedFamily = getCurrentIconFamily();
+  return cachedFamily;
+}
+function getIconFamilyServerSnapshot() {
+  return DEFAULT_FAMILY;
+}
+function useIconFamily() {
+  return useSyncExternalStore(
+    subscribeIconFamily,
+    getIconFamilySnapshot,
+    getIconFamilyServerSnapshot
+  );
+}
 function kebabToPascal(name) {
   return name.split("-").map((part) => {
     if (/^\d+$/.test(part)) return part;
     return part.charAt(0).toUpperCase() + part.slice(1);
   }).join("");
 }
-var resolvedCache = /* @__PURE__ */ new Map();
-function resolveIcon(name) {
-  const cached = resolvedCache.get(name);
-  if (cached) return cached;
-  const resolved = doResolve(name);
-  resolvedCache.set(name, resolved);
-  return resolved;
-}
-function doResolve(name) {
-  if (iconAliases[name]) return iconAliases[name];
-  const pascalName = kebabToPascal(name);
-  const directLookup = LucideIcons[pascalName];
-  if (directLookup && typeof directLookup === "object") return directLookup;
-  const asIs = LucideIcons[name];
+var lucideAliases = {
+  close: LucideIcons.X,
+  trash: LucideIcons.Trash2,
+  loader: LucideIcons.Loader2,
+  stop: LucideIcons.Square,
+  volume: LucideIcons.Volume2,
+  "volume-off": LucideIcons.VolumeX,
+  refresh: LucideIcons.RefreshCw,
+  share: LucideIcons.Share2,
+  "sort-asc": LucideIcons.ArrowUpNarrowWide,
+  "sort-desc": LucideIcons.ArrowDownNarrowWide
+};
+function resolveLucide(name) {
+  if (lucideAliases[name]) return lucideAliases[name];
+  const pascal = kebabToPascal(name);
+  const lucideMap = LucideIcons;
+  const direct = lucideMap[pascal];
+  if (direct && typeof direct === "object") return direct;
+  const asIs = lucideMap[name];
   if (asIs && typeof asIs === "object") return asIs;
   return LucideIcons.HelpCircle;
 }
+var phosphorAliases = {
+  // lucide name → phosphor PascalCase name
+  search: "MagnifyingGlass",
+  close: "X",
+  loader: "CircleNotch",
+  refresh: "ArrowsClockwise",
+  "sort-asc": "SortAscending",
+  "sort-desc": "SortDescending",
+  "chevron-down": "CaretDown",
+  "chevron-up": "CaretUp",
+  "chevron-left": "CaretLeft",
+  "chevron-right": "CaretRight",
+  "help-circle": "Question",
+  "alert-triangle": "Warning",
+  "alert-circle": "WarningCircle",
+  "check-circle": "CheckCircle",
+  "x-circle": "XCircle",
+  edit: "PencilSimple",
+  pencil: "PencilSimple",
+  trash: "Trash",
+  send: "PaperPlaneRight",
+  external: "ArrowSquareOut",
+  "external-link": "ArrowSquareOut",
+  plus: "Plus",
+  minus: "Minus",
+  x: "X",
+  check: "Check",
+  star: "Star",
+  heart: "Heart",
+  home: "House",
+  user: "User",
+  users: "Users",
+  settings: "Gear",
+  menu: "List",
+  "arrow-up": "ArrowUp",
+  "arrow-down": "ArrowDown",
+  "arrow-left": "ArrowLeft",
+  "arrow-right": "ArrowRight",
+  copy: "Copy",
+  download: "DownloadSimple",
+  upload: "UploadSimple",
+  filter: "Funnel",
+  calendar: "Calendar",
+  clock: "Clock",
+  bell: "Bell",
+  mail: "Envelope",
+  envelope: "Envelope",
+  lock: "Lock",
+  unlock: "LockOpen",
+  eye: "Eye",
+  "eye-off": "EyeSlash",
+  more: "DotsThree",
+  "more-vertical": "DotsThreeVertical",
+  info: "Info",
+  warning: "Warning",
+  error: "WarningCircle"
+};
+function resolvePhosphor(name, weight) {
+  const target = phosphorAliases[name] ?? kebabToPascal(name);
+  const map = PhosphorIcons;
+  const PhosphorComp = map[target];
+  if (!PhosphorComp || typeof PhosphorComp !== "object") return null;
+  const Component = PhosphorComp;
+  const Adapter = (props) => /* @__PURE__ */ jsx(
+    Component,
+    {
+      weight,
+      className: props.className,
+      style: props.style,
+      size: props.size ?? "1em"
+    }
+  );
+  Adapter.displayName = `Phosphor.${target}.${weight}`;
+  return Adapter;
+}
+var tablerAliases = {
+  // lucide name → tabler suffix (after the `Icon` prefix)
+  search: "Search",
+  close: "X",
+  loader: "Loader2",
+  refresh: "Refresh",
+  "sort-asc": "SortAscending",
+  "sort-desc": "SortDescending",
+  "chevron-down": "ChevronDown",
+  "chevron-up": "ChevronUp",
+  "chevron-left": "ChevronLeft",
+  "chevron-right": "ChevronRight",
+  "help-circle": "HelpCircle",
+  "alert-triangle": "AlertTriangle",
+  "alert-circle": "AlertCircle",
+  "check-circle": "CircleCheck",
+  "x-circle": "CircleX",
+  edit: "Pencil",
+  trash: "Trash",
+  send: "Send",
+  external: "ExternalLink",
+  plus: "Plus",
+  x: "X",
+  check: "Check",
+  star: "Star",
+  heart: "Heart",
+  home: "Home",
+  user: "User",
+  users: "Users",
+  settings: "Settings",
+  menu: "Menu2",
+  copy: "Copy",
+  download: "Download",
+  upload: "Upload",
+  filter: "Filter",
+  calendar: "Calendar",
+  clock: "Clock",
+  bell: "Bell",
+  mail: "Mail",
+  envelope: "Mail",
+  lock: "Lock",
+  unlock: "LockOpen",
+  eye: "Eye",
+  "eye-off": "EyeOff",
+  more: "Dots",
+  "more-vertical": "DotsVertical",
+  info: "InfoCircle"
+};
+function resolveTabler(name) {
+  const suffix = tablerAliases[name] ?? kebabToPascal(name);
+  const target = `Icon${suffix}`;
+  const map = TablerIcons;
+  const TablerComp = map[target];
+  if (!TablerComp || typeof TablerComp !== "object") return null;
+  const Component = TablerComp;
+  const Adapter = (props) => /* @__PURE__ */ jsx(
+    Component,
+    {
+      stroke: props.strokeWidth ?? 1.5,
+      className: props.className,
+      style: props.style,
+      size: props.size ?? 24
+    }
+  );
+  Adapter.displayName = `Tabler.${target}`;
+  return Adapter;
+}
+var faAliases = {
+  // lucide name → fa-solid suffix (after the `Fa` prefix)
+  search: "Search",
+  close: "Times",
+  x: "Times",
+  loader: "Spinner",
+  refresh: "Sync",
+  "sort-asc": "SortAmountUp",
+  "sort-desc": "SortAmountDown",
+  "chevron-down": "ChevronDown",
+  "chevron-up": "ChevronUp",
+  "chevron-left": "ChevronLeft",
+  "chevron-right": "ChevronRight",
+  "help-circle": "QuestionCircle",
+  "alert-triangle": "ExclamationTriangle",
+  "alert-circle": "ExclamationCircle",
+  "check-circle": "CheckCircle",
+  "x-circle": "TimesCircle",
+  edit: "Edit",
+  pencil: "Pencil",
+  trash: "Trash",
+  send: "PaperPlane",
+  external: "ExternalLinkAlt",
+  plus: "Plus",
+  minus: "Minus",
+  check: "Check",
+  star: "Star",
+  heart: "Heart",
+  home: "Home",
+  user: "User",
+  users: "Users",
+  settings: "Cog",
+  menu: "Bars",
+  "arrow-up": "ArrowUp",
+  "arrow-down": "ArrowDown",
+  "arrow-left": "ArrowLeft",
+  "arrow-right": "ArrowRight",
+  copy: "Copy",
+  download: "Download",
+  upload: "Upload",
+  filter: "Filter",
+  calendar: "Calendar",
+  clock: "Clock",
+  bell: "Bell",
+  mail: "Envelope",
+  envelope: "Envelope",
+  lock: "Lock",
+  unlock: "LockOpen",
+  eye: "Eye",
+  "eye-off": "EyeSlash",
+  more: "EllipsisH",
+  "more-vertical": "EllipsisV",
+  info: "InfoCircle",
+  warning: "ExclamationTriangle"
+};
+function resolveFa(name) {
+  const suffix = faAliases[name] ?? kebabToPascal(name);
+  const target = `Fa${suffix}`;
+  const map = FaIcons;
+  const FaComp = map[target];
+  if (!FaComp || typeof FaComp !== "function") return null;
+  const Component = FaComp;
+  const Adapter = (props) => /* @__PURE__ */ jsx(
+    Component,
+    {
+      className: props.className,
+      style: props.style,
+      size: props.size ?? "1em"
+    }
+  );
+  Adapter.displayName = `Fa.${target}`;
+  return Adapter;
+}
+var warned = /* @__PURE__ */ new Set();
+function warnFallback(name, family) {
+  const key = `${family}::${name}`;
+  if (warned.has(key)) return;
+  warned.add(key);
+  if (typeof console !== "undefined") {
+    console.warn(
+      `[iconFamily] No '${name}' mapping in family '${family}'; falling back to lucide. Add an alias in lib/iconFamily.ts.`
+    );
+  }
+}
+function makeLucideAdapter(name) {
+  const LucideComp = resolveLucide(name);
+  const Adapter = (props) => /* @__PURE__ */ jsx(
+    LucideComp,
+    {
+      className: props.className,
+      strokeWidth: props.strokeWidth,
+      style: props.style,
+      size: props.size
+    }
+  );
+  Adapter.displayName = `Lucide.${name}`;
+  return Adapter;
+}
+function resolveIconForFamily(name, family) {
+  switch (family) {
+    case "lucide":
+      return makeLucideAdapter(name);
+    case "phosphor-outline": {
+      const p = resolvePhosphor(name, "regular");
+      if (p) return p;
+      warnFallback(name, family);
+      return makeLucideAdapter(name);
+    }
+    case "phosphor-fill": {
+      const p = resolvePhosphor(name, "fill");
+      if (p) return p;
+      warnFallback(name, family);
+      return makeLucideAdapter(name);
+    }
+    case "phosphor-duotone": {
+      const p = resolvePhosphor(name, "duotone");
+      if (p) return p;
+      warnFallback(name, family);
+      return makeLucideAdapter(name);
+    }
+    case "tabler": {
+      const t = resolveTabler(name);
+      if (t) return t;
+      warnFallback(name, family);
+      return makeLucideAdapter(name);
+    }
+    case "fa-solid": {
+      const f = resolveFa(name);
+      if (f) return f;
+      warnFallback(name, family);
+      return makeLucideAdapter(name);
+    }
+  }
+}
 var sizeClasses = {
   xs: "w-3 h-3",
   sm: "w-4 h-4",
@@ -3031,22 +3359,50 @@ var Icon = ({
   strokeWidth,
   style
 }) => {
-  const IconComponent = icon ?? (name ? resolveIcon(name) : LucideIcons.HelpCircle);
+  const family = useIconFamily();
+  const RenderedComponent = React7.useMemo(() => {
+    if (icon) return null;
+    return name ? resolveIconForFamily(name, family) : null;
+  }, [icon, name, family]);
   const effectiveStrokeWidth = strokeWidth ?? void 0;
+  const inlineStyle = {
+    ...effectiveStrokeWidth === void 0 ? { strokeWidth: "var(--icon-stroke-width, 2)" } : {},
+    ...style
+  };
+  const composedClassName = cn(
+    sizeClasses[size],
+    animationClasses[animation],
+    color ? color : "text-current",
+    className
+  );
+  if (icon) {
+    const Direct = icon;
+    return /* @__PURE__ */ jsx(
+      Direct,
+      {
+        className: composedClassName,
+        strokeWidth: effectiveStrokeWidth,
+        style: inlineStyle
+      }
+    );
+  }
+  if (RenderedComponent) {
+    return /* @__PURE__ */ jsx(
+      RenderedComponent,
+      {
+        className: composedClassName,
+        strokeWidth: effectiveStrokeWidth,
+        style: inlineStyle
+      }
+    );
+  }
+  const Fallback = LucideIcons.HelpCircle;
   return /* @__PURE__ */ jsx(
-    IconComponent,
+    Fallback,
     {
-      className: cn(
-        sizeClasses[size],
-        animationClasses[animation],
-        color ? color : "text-current",
-        className
-      ),
+      className: composedClassName,
       strokeWidth: effectiveStrokeWidth,
-      style: {
-        ...effectiveStrokeWidth === void 0 ? { strokeWidth: "var(--icon-stroke-width, 2)" } : {},
-        ...style
-      }
+      style: inlineStyle
     }
   );
 };
@@ -3114,14 +3470,13 @@ var iconSizeStyles = {
 function resolveIconProp(value, sizeClass) {
   if (!value) return null;
   if (typeof value === "string") {
-    const Resolved = resolveIcon(value);
-    return Resolved ? /* @__PURE__ */ jsx(Resolved, { className: sizeClass }) : null;
+    return /* @__PURE__ */ jsx(Icon, { name: value, className: sizeClass });
   }
   if (typeof value === "function") {
     const IconComp = value;
     return /* @__PURE__ */ jsx(IconComp, { className: sizeClass });
   }
-  if (React5.isValidElement(value)) {
+  if (React7.isValidElement(value)) {
     return value;
   }
   if (typeof value === "object" && value !== null && "render" in value) {
@@ -3130,7 +3485,7 @@ function resolveIconProp(value, sizeClass) {
   }
   return value;
 }
-var Button = React5.forwardRef(
+var Button = React7.forwardRef(
   ({
     className,
     variant = "primary",
@@ -3233,7 +3588,7 @@ var shadowStyles2 = {
   md: "shadow",
   lg: "shadow-elevation-dialog"
 };
-var Card = React5.forwardRef(
+var Card = React7.forwardRef(
   ({
     className,
     variant = "bordered",
@@ -3269,9 +3624,9 @@ var Card = React5.forwardRef(
   }
 );
 Card.displayName = "Card";
-var CardHeader = React5.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx("div", { ref, className: cn("mb-4", className), ...props }));
+var CardHeader = React7.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx("div", { ref, className: cn("mb-4", className), ...props }));
 CardHeader.displayName = "CardHeader";
-var CardTitle = React5.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(
+var CardTitle = React7.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(
   "h3",
   {
     ref,
@@ -3284,11 +3639,11 @@ var CardTitle = React5.forwardRef(({ className, ...props }, ref) => /* @__PURE__
   }
 ));
 CardTitle.displayName = "CardTitle";
-var CardContent = React5.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx("div", { ref, className: cn("", className), ...props }));
+var CardContent = React7.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx("div", { ref, className: cn("", className), ...props }));
 CardContent.displayName = "CardContent";
 var CardBody = CardContent;
 CardBody.displayName = "CardBody";
-var CardFooter = React5.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(
+var CardFooter = React7.forwardRef(({ className, ...props }, ref) => /* @__PURE__ */ jsx(
   "div",
   {
     ref,
@@ -3367,7 +3722,7 @@ var Divider = ({
   );
 };
 Divider.displayName = "Divider";
-var Input = React5.forwardRef(
+var Input = React7.forwardRef(
   ({
     className,
     inputType,
@@ -3417,7 +3772,7 @@ var Input = React5.forwardRef(
             ]
           }
         ),
-        /* @__PURE__ */ jsx("div", { className: "absolute inset-y-0 right-0 pr-3 flex items-center pointer-events-none text-muted-foreground", children: /* @__PURE__ */ jsx(ChevronDown, { className: "h-icon-default w-icon-default" }) })
+        /* @__PURE__ */ jsx("div", { className: "absolute inset-y-0 right-0 pr-3 flex items-center pointer-events-none text-muted-foreground", children: /* @__PURE__ */ jsx(Icon, { name: "chevron-down", className: "h-icon-default w-icon-default" }) })
       ] });
     }
     if (type === "textarea") {
@@ -3471,7 +3826,7 @@ var Input = React5.forwardRef(
           type: "button",
           onClick: onClear,
           className: "absolute inset-y-0 right-0 pr-3 flex items-center text-muted-foreground hover:text-foreground",
-          children: /* @__PURE__ */ jsx(X, { className: "h-icon-default w-icon-default" })
+          children: /* @__PURE__ */ jsx(Icon, { name: "x", className: "h-icon-default w-icon-default" })
         }
       ),
       rightIcon && !showClearButton && /* @__PURE__ */ jsx("div", { className: "absolute inset-y-0 right-0 pr-3 flex items-center text-muted-foreground", children: rightIcon })
@@ -3635,7 +3990,7 @@ var DocBreadcrumb = ({
       "aria-label": "Breadcrumb",
       children: /* @__PURE__ */ jsx(HStack, { gap: "xs", align: "center", wrap: true, children: items.map((item, idx) => {
         const isLast = idx === items.length - 1;
-        return /* @__PURE__ */ jsxs(React5.Fragment, { children: [
+        return /* @__PURE__ */ jsxs(React7.Fragment, { children: [
           idx > 0 && /* @__PURE__ */ jsx(
             Icon,
             {

package/dist/lib/iconFamily.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Icon family runtime resolver (Layer 1 Iconography axis).
+ *
+ * Reads the active `--icon-family` CSS variable from the document element and
+ * dispatches a canonical icon name (kebab-case, matching lucide's vocabulary)
+ * to the equivalent component in the active family. Subscribes to data-theme
+ * attribute changes via MutationObserver so a theme switch re-renders icons
+ * into the new family without a page reload.
+ *
+ * Canonical name = lucide name. Per-family alias tables resolve cross-family
+ * naming differences (e.g. lucide's `search` is phosphor's `MagnifyingGlass`).
+ * For names not mapped in the active family, falls back to lucide and logs a
+ * console.warn — preserves semantic over family purity.
+ *
+ * See `docs/Almadar_Std_Variations.md` §2 and `themes/_contract.md`.
+ */
+import React from 'react';
+import type { IconFamily as IconFamilyType } from '@almadar/core';
+export type IconFamily = IconFamilyType;
+/** Adapter props that EVERY family-specific icon component accepts at this layer. */
+export interface RenderedIconProps {
+    className?: string;
+    strokeWidth?: number;
+    size?: number;
+    style?: React.CSSProperties;
+}
+/** Read --icon-family from <html> at runtime. Returns 'lucide' on SSR. */
+export declare function getCurrentIconFamily(): IconFamily;
+/** React hook: returns the active icon family, re-renders on theme switch. */
+export declare function useIconFamily(): IconFamily;
+/**
+ * Dispatch a canonical icon name to the right family component.
+ * Falls back to lucide (with console.warn) when the family has no mapping.
+ */
+export declare function resolveIconForFamily(name: string, family: IconFamily): React.ComponentType<RenderedIconProps>;
+/**
+ * Resolve a canonical icon name to a family-aware component. The returned
+ * component re-renders the icon into the active family's library on theme
+ * switch (via useIconFamily's MutationObserver subscription).
+ */
+export declare function useResolvedIcon(name: string): React.ComponentType<RenderedIconProps>;