@axzydev/axzy_ui_system 1.3.0 → 1.3.2

package/src/sandbox/NotFoundShowcase.tsx

@@ -0,0 +1,70 @@
+import { FaHome, FaLayerGroup } from "react-icons/fa";
+import ITButton from "@/components/atoms/button/button";
+import ITFlex from "@/components/atoms/flex/flex";
+import ITStack from "@/components/atoms/stack/stack";
+import ITText from "@/components/atoms/text/text";
+
+/** Props for the sandbox 404 page. */
+export interface NotFoundShowcaseProps {
+  /** Raw hash that failed to resolve (shown inside a `<code>` block). */
+  attempted: string;
+  /** Navigate back to the `#ui-system` landing. */
+  onGoLanding: () => void;
+  /** Navigate back to the portfolio. */
+  onGoPortfolio: () => void;
+}
+
+/**
+ * Sandbox 404 page rendered when a hash route does not resolve to a page.
+ *
+ * Shows the attempted path, a friendly message, and buttons to recover.
+ */
+export default function NotFoundShowcase({
+  attempted,
+  onGoLanding,
+  onGoPortfolio,
+}: NotFoundShowcaseProps) {
+  return (
+    <div className="animate-fadeIn flex min-h-[60vh] items-center justify-center px-4">
+      <ITStack spacing={5} className="w-full max-w-xl text-center items-center">
+        <ITText
+          as="div"
+          className="!text-7xl !font-extrabold !tracking-tight bg-gradient-to-br from-primary-500 via-primary-600 to-purple-600 bg-clip-text text-transparent"
+        >
+          404
+        </ITText>
+
+        <ITStack spacing={2} className="items-center">
+          <ITText as="h1" className="!text-2xl !font-bold text-slate-900 dark:text-white">
+            Ruta no encontrada
+          </ITText>
+          <ITText as="p" className="!text-sm text-slate-500 dark:text-slate-400">
+            No existe una página para este hash. Revisa el enlace o vuelve al inicio.
+          </ITText>
+          <code className="mt-1 max-w-full truncate rounded-lg border border-slate-200 bg-slate-50 px-3 py-1.5 font-mono text-xs text-slate-600 dark:border-slate-700 dark:bg-slate-900 dark:text-slate-300">
+            {attempted || "#"}
+          </code>
+        </ITStack>
+
+        <ITFlex gap={3} wrap="wrap" justify="center" align="center">
+          <ITButton
+            variant="filled"
+            color="primary"
+            icon={<FaHome size={13} />}
+            onClick={onGoLanding}
+          >
+            Volver al inicio
+          </ITButton>
+          <ITButton
+            variant="outlined"
+            color="secondary"
+            icon={<FaLayerGroup size={13} />}
+            onClick={onGoPortfolio}
+          >
+            Ver portafolio
+          </ITButton>
+        </ITFlex>
+      </ITStack>
+    </div>
+  );
+}

package/src/sandbox/TopbarSearch.tsx

@@ -0,0 +1,85 @@
+import type { ChangeEvent } from "react";
+import { FaSearch, FaTimes } from "react-icons/fa";
+import ITButton from "@/components/atoms/button/button";
+import ITInput from "@/components/atoms/input/input";
+
+/** Props for the sandbox topbar search filter. */
+export interface TopbarSearchProps {
+  /** Current (live) search term shown in the input. */
+  value: string;
+  /** Called with the new term on every keystroke. */
+  onChange: (value: string) => void;
+  /** Called when the user clears the search. */
+  onClear: () => void;
+  /** Number of matching navigation entries for the current term. */
+  resultCount: number;
+  /**
+   * When true, the debounced filter has not caught up with the live term yet.
+   * The result count is hidden so it never announces a stale number.
+   */
+  pending?: boolean;
+  /** Additional CSS classes on the form wrapper. Defaults to `"w-full"`. */
+  className?: string;
+}
+
+/**
+ * Topbar search box that filters every sandbox component live.
+ *
+ * Renders a search input with a clear button and an accessible live-region
+ * announcement of the result count. It lives in the topbar center slot
+ * (`topBar.centerContent`), so it stays visible while the sidebar collapses.
+ */
+export default function TopbarSearch({
+  value,
+  onChange,
+  onClear,
+  resultCount,
+  pending = false,
+  className = "w-full",
+}: TopbarSearchProps) {
+  const isActive = value.trim().length > 0;
+  const showCount = isActive && !pending;
+
+  return (
+    <form
+      role="search"
+      onSubmit={(event) => event.preventDefault()}
+      className={className}
+    >
+      <div className="flex items-center gap-1.5">
+        <div className="flex-1 min-w-0">
+          <ITInput
+            name="sandbox-topbar-search"
+            label="Buscar componentes"
+            labelClassName="sr-only"
+            placeholder="Buscar componente…"
+            value={value}
+            onChange={(event: ChangeEvent<HTMLInputElement>) =>
+              onChange(event.target.value)
+            }
+            iconLeft={<FaSearch size={12} />}
+            size="sm"
+            containerClassName="w-full"
+          />
+        </div>
+
+        {isActive && (
+          <ITButton
+            variant="text"
+            color="danger"
+            size="sm"
+            ariaLabel="Limpiar búsqueda"
+            onClick={onClear}
+            className="flex-shrink-0"
+          >
+            <FaTimes size={11} />
+          </ITButton>
+        )}
+      </div>
+
+      <span role="status" aria-live="polite" className="sr-only">
+        {showCount ? `${resultCount} resultados` : ""}
+      </span>
+    </form>
+  );
+}

package/src/sandbox/navigation.ts

@@ -0,0 +1,148 @@
+/**
+ * Sandbox navigation catalog (dev-only, NOT part of the published package).
+ *
+ * Plain data only — no JSX, no icons. Icons live in the consumer (`App.tsx`)
+ * keyed by group id so this module stays serializable and router-friendly.
+ */
+
+/** A single component page inside a sandbox group. */
+export interface SandboxSubItem {
+  /** Stable item id used in the hash route (`#ui-system/<group>/<id>`). */
+  id: string;
+  /** Human-readable label shown in the sidebar and landing. */
+  label: string;
+}
+
+/** A family of component pages (e.g. forms, data visualization). */
+export interface SandboxGroup {
+  /** Stable group id used internally and by `GROUP_SLUGS`. */
+  id: string;
+  /** Human-readable group label. */
+  label: string;
+  /** Pages belonging to this group. */
+  subitems: SandboxSubItem[];
+}
+
+/** All sandbox groups and their pages, transcribed from the legacy App catalog. */
+export const SANDBOX_GROUPS: SandboxGroup[] = [
+  {
+    id: "general",
+    label: "General",
+    subitems: [
+      { id: "getting-started", label: "Getting Started" },
+      { id: "sizes", label: "Medidas · sm / md / lg" },
+    ],
+  },
+  {
+    id: "struc",
+    label: "Estructura & Layout",
+    subitems: [
+      { id: "layout", label: "ITLayout & ITNavbar" },
+      { id: "stack", label: "ITStack" },
+      { id: "flex", label: "ITFlex" },
+      { id: "grid", label: "ITGrid" },
+      { id: "card", label: "ITCard" },
+      { id: "text", label: "ITText" },
+      { id: "accordion", label: "ITAccordion" },
+      { id: "pageheader", label: "ITPageHeader" },
+      { id: "page", label: "ITPage" },
+      { id: "screen-dashboard", label: "Dashboard Ejemplo" },
+      { id: "screen-form", label: "Formulario Ejemplo" },
+    ],
+  },
+  {
+    id: "forms",
+    label: "Formularios & Inputs",
+    subitems: [
+      { id: "button", label: "ITButton" },
+      { id: "input", label: "ITInput" },
+      { id: "select", label: "ITSelect" },
+      { id: "searchselect", label: "ITSearchSelect" },
+      { id: "multiselect", label: "ITMultiSelect" },
+      { id: "chipinput", label: "ITChipInput" },
+      { id: "field", label: "ITField" },
+      { id: "datepicker", label: "ITDatePicker" },
+      { id: "timepicker", label: "ITTimePicker" },
+      { id: "maskedinput", label: "ITMaskedInput" },
+      { id: "calendar", label: "ITCalendar" },
+      { id: "slidetoggle", label: "ITSlideToggle" },
+      { id: "dropfile", label: "ITDropfile" },
+      { id: "wysiwyg", label: "ITWysiwyg" },
+      { id: "formbuilder", label: "ITFormBuilder" },
+    ],
+  },
+  {
+    id: "data",
+    label: "Visualización Datos",
+    subitems: [
+      { id: "table", label: "ITTable" },
+      { id: "datatable", label: "ITDataTable" },
+      { id: "badget", label: "ITBadget" },
+      { id: "chip", label: "ITChip" },
+      { id: "image", label: "ITImage" },
+    ],
+  },
+  {
+    id: "nav",
+    label: "Navegación & Control",
+    subitems: [
+      { id: "tabs", label: "ITTabs" },
+      { id: "stepper", label: "ITStepper" },
+      { id: "pagination", label: "ITPagination" },
+      { id: "triplefilter", label: "ITTripleFilter" },
+      { id: "dropdownmenu", label: "ITDropdownMenu" },
+    ],
+  },
+  {
+    id: "feed",
+    label: "Feedback & Sistema",
+    subitems: [
+      { id: "dialog", label: "ITDialog" },
+      { id: "toast", label: "ITToast" },
+      { id: "loader", label: "ITLoader" },
+      { id: "themeprovider", label: "ITThemeProvider" },
+    ],
+  },
+];
+
+/** Readable group-id → URL-slug map. */
+export const GROUP_SLUGS: Record<string, string> = {
+  general: "general",
+  struc: "structure",
+  forms: "forms",
+  data: "viewdata",
+  nav: "navigation",
+  feed: "feedback",
+};
+
+/** Inverse of `GROUP_SLUGS`: URL-slug → group-id. */
+export const SLUG_TO_GROUP: Record<string, string> = Object.fromEntries(
+  Object.entries(GROUP_SLUGS).map(([id, slug]) => [slug, id]),
+);
+
+/** Look up a group by its internal id. Returns `null` when unknown. */
+export function groupById(id: string): SandboxGroup | null {
+  return SANDBOX_GROUPS.find((group) => group.id === id) ?? null;
+}
+
+/** Look up a group by its URL slug. Returns `null` when unknown. */
+export function groupBySlug(slug: string): SandboxGroup | null {
+  const id = SLUG_TO_GROUP[slug];
+  return id ? groupById(id) : null;
+}
+
+/** First item id of a group, or `null` when the group is unknown/empty. */
+export function firstItemOf(groupId: string): string | null {
+  return groupById(groupId)?.subitems[0]?.id ?? null;
+}
+
+/** Whether `itemId` exists inside `groupId`. */
+export function isValidItem(groupId: string, itemId: string): boolean {
+  return groupById(groupId)?.subitems.some((sub) => sub.id === itemId) ?? false;
+}
+
+/** Total number of pages across every group (derived — never hardcoded). */
+export const TOTAL_ITEMS = SANDBOX_GROUPS.reduce(
+  (total, group) => total + group.subitems.length,
+  0,
+);

package/src/sandbox/useHashRoute.ts

@@ -0,0 +1,149 @@
+import { useCallback, useEffect, useState } from "react";
+import { GROUP_SLUGS, groupBySlug, isValidItem } from "./navigation";
+
+/** Top-level sandbox views. `home` is the untouched portfolio. */
+export type SandboxView = "home" | "ui-system";
+
+/** Parsed representation of `window.location.hash`. */
+export interface HashRoute {
+  /** Which top-level view the hash points at. */
+  view: SandboxView;
+  /** Internal group id (`forms`, `data`, …) or `null` on the landing. */
+  group: string | null;
+  /** Item id (`input`, `table`, …) or `null` for a group-only route. */
+  item: string | null;
+  /** Raw hash exactly as read from the URL (used by the 404 page). */
+  raw: string;
+  /** Whether the route resolved to a real page. `false` → render 404. */
+  valid: boolean;
+}
+
+/**
+ * Parse a location hash into a `HashRoute`.
+ *
+ * Rules:
+ * - empty / first segment !== `ui-system` → portfolio (`home`).
+ * - `#ui-system` → landing.
+ * - `#ui-system/<group-slug>` → group landing (valid, `item` null).
+ * - `#ui-system/<group-slug>/<item-id>` → page (valid) or 404 when unknown.
+ * - more than 3 segments → 404.
+ */
+export function parseHash(hash: string): HashRoute {
+  const raw = hash;
+  const clean = hash.startsWith("#") ? hash.slice(1) : hash;
+  const parts = clean.split("/").filter(Boolean);
+
+  if (parts.length === 0 || parts[0] !== "ui-system") {
+    return { view: "home", group: null, item: null, raw, valid: true };
+  }
+
+  if (parts.length === 1) {
+    return { view: "ui-system", group: null, item: null, raw, valid: true };
+  }
+
+  if (parts.length === 2) {
+    const group = groupBySlug(parts[1]);
+    if (!group) {
+      return { view: "ui-system", group: null, item: null, raw, valid: false };
+    }
+    return { view: "ui-system", group: group.id, item: null, raw, valid: true };
+  }
+
+  if (parts.length === 3) {
+    const group = groupBySlug(parts[1]);
+    if (!group || !isValidItem(group.id, parts[2])) {
+      return {
+        view: "ui-system",
+        group: group?.id ?? null,
+        item: null,
+        raw,
+        valid: false,
+      };
+    }
+    return { view: "ui-system", group: group.id, item: parts[2], raw, valid: true };
+  }
+
+  return { view: "ui-system", group: null, item: null, raw, valid: false };
+}
+
+/** Build a hash for a group/item pair, translating the group id to its slug. */
+export function buildHash(group: string, item?: string): string {
+  const slug = GROUP_SLUGS[group] ?? group;
+  return item ? `#ui-system/${slug}/${item}` : `#ui-system/${slug}`;
+}
+
+/** Navigation options shared by every `goTo*` helper. */
+export interface GoToOptions {
+  /** Replace the current history entry instead of pushing a new one. */
+  replace?: boolean;
+}
+
+/** Result of `useHashRoute`. */
+export interface UseHashRouteResult {
+  /** Current parsed route. */
+  route: HashRoute;
+  /** Navigate to a component page. */
+  goToItem: (group: string, item: string, options?: GoToOptions) => void;
+  /** Navigate to the `#ui-system` landing. */
+  goToLanding: (options?: GoToOptions) => void;
+  /** Navigate back to the portfolio (strips the hash). */
+  goToPortfolio: (options?: GoToOptions) => void;
+}
+
+/**
+ * Zero-dependency hash router for the dev sandbox.
+ *
+ * Reads the initial hash on mount (deep links + refresh work), listens to both
+ * `hashchange` and `popstate` (so back/forward work no matter how the entry was
+ * created) and cleans both listeners up on unmount (StrictMode-safe).
+ */
+export function useHashRoute(): UseHashRouteResult {
+  const [route, setRoute] = useState<HashRoute>(() =>
+    parseHash(typeof window === "undefined" ? "" : window.location.hash),
+  );
+
+  useEffect(() => {
+    const sync = () => setRoute(parseHash(window.location.hash));
+    window.addEventListener("hashchange", sync);
+    window.addEventListener("popstate", sync);
+    return () => {
+      window.removeEventListener("hashchange", sync);
+      window.removeEventListener("popstate", sync);
+    };
+  }, []);
+
+  const navigate = useCallback((hash: string, options?: GoToOptions) => {
+    if (options?.replace) {
+      window.history.replaceState(null, "", hash);
+      setRoute(parseHash(hash));
+      return;
+    }
+    window.location.hash = hash;
+  }, []);
+
+  const goToItem = useCallback(
+    (group: string, item: string, options?: GoToOptions) => {
+      navigate(buildHash(group, item), options);
+    },
+    [navigate],
+  );
+
+  const goToLanding = useCallback(
+    (options?: GoToOptions) => {
+      navigate("#ui-system", options);
+    },
+    [navigate],
+  );
+
+  const goToPortfolio = useCallback((options?: GoToOptions) => {
+    const url = `${window.location.pathname}${window.location.search}`;
+    if (options?.replace) {
+      window.history.replaceState(null, "", url);
+    } else {
+      window.history.pushState(null, "", url);
+    }
+    setRoute(parseHash(""));
+  }, []);
+
+  return { route, goToItem, goToLanding, goToPortfolio };
+}