flet-box 0.0.0-stage → 1.0.2

package/src/services/http.js

@@ -0,0 +1,350 @@
+// FletBox/services/http.js
+
+/*
+ * HTTP requests module - Python requests style
+ *
+ * @example
+ * // GET
+ * const users = await httpGet('https://api.example.com/users');
+ *
+ * // POST
+ * const newUser = await httpPost('https://api.example.com/users', {
+ *     body: { name: 'Juan', email: 'juan@email.com' }
+ * });
+ *
+ * // PUT
+ * const updated = await httpPut('https://api.example.com/users/1', {
+ *     body: { name: 'Juan Carlos' }
+ * });
+ *
+ * // DELETE
+ * await httpDelete('https://api.example.com/users/1');
+ *
+ * // With headers
+ * const data = await httpGet('https://api.example.com/protected', {
+ *     headers: { 'Authorization': 'Bearer token123' }
+ * });
+ * // FletBox/services/http.js
+ *
+ * HTTP requests module - Python requests style
+ *
+ * @description
+ * Module for making HTTP requests with a simple and consistent syntax.
+ * Supports GET, POST, PUT, PATCH, DELETE with timeout, headers, and params.
+ *
+ * @example
+ * // 1. GET - Fetch data on start
+ * import { useEffect, useState } from 'react';
+ * import { Container, Text, httpGet } from 'fletbox';
+ *
+ * function UsersScreen() {
+ *     const [users, setUsers] = useState([]);
+ *
+ *     useEffect(() => {
+ *         async function loadUsers() {
+ *             const data = await httpGet('https://jsonplaceholder.typicode.com/users');
+ *             setUsers(data);
+ *         }
+ *         loadUsers();
+ *     }, []);
+ *
+ *     return (
+ *         <Container>
+ *             <Text>Total users: {users.length}</Text>
+ *         </Container>
+ *     );
+ * }
+ *
+ * @example
+ * // 2. POST - Create data
+ * import { Button, Container, Text, httpPost } from 'fletbox';
+ *
+ * function CreateUserScreen() {
+ *     const [result, setResult] = useState(null);
+ *
+ *     const createUser = async () => {
+ *         const newUser = await httpPost('https://jsonplaceholder.typicode.com/users', {
+ *             body: { name: 'Juan', email: 'juan@email.com' }
+ *         });
+ *         setResult(newUser);
+ *     };
+ *
+ *     return (
+ *         <Container>
+ *             <Button label="Create User" onPress={createUser} />
+ *             {result && <Text>User created ID: {result.id}</Text>}
+ *         </Container>
+ *     );
+ * }
+ *
+ * @example
+ * // 3. PUT - Update full data
+ * import { Button, Container, Text, httpPut } from 'fletbox';
+ *
+ * function UpdateUserScreen() {
+ *     const [result, setResult] = useState(null);
+ *
+ *     const updateUser = async () => {
+ *         const updated = await httpPut('https://jsonplaceholder.typicode.com/users/1', {
+ *             body: { name: 'Carlos', email: 'carlos@email.com' }
+ *         });
+ *         setResult(updated);
+ *     };
+ *
+ *     return (
+ *         <Container>
+ *             <Button label="Update User" onPress={updateUser} />
+ *             {result && <Text>User updated: {result.name}</Text>}
+ *         </Container>
+ *     );
+ * }
+ *
+ * @example
+ * // 4. PATCH - Update partial data
+ * import { Button, Container, Text, httpPatch } from 'fletbox';
+ *
+ * function PatchUserScreen() {
+ *     const [result, setResult] = useState(null);
+ *
+ *     const patchUser = async () => {
+ *         const patched = await httpPatch('https://jsonplaceholder.typicode.com/users/1', {
+ *             body: { email: 'nuevo@email.com' }
+ *         });
+ *         setResult(patched);
+ *     };
+ *
+ *     return (
+ *         <Container>
+ *             <Button label="Update Email" onPress={patchUser} />
+ *             {result && <Text>Email updated: {result.email}</Text>}
+ *         </Container>
+ *     );
+ * }
+ *
+ * @example
+ * // 5. DELETE - Delete data
+ * import { Button, Container, Text, httpDelete } from 'fletbox';
+ *
+ * function DeleteUserScreen() {
+ *     const [deleted, setDeleted] = useState(false);
+ *
+ *     const deleteUser = async () => {
+ *         await httpDelete('https://jsonplaceholder.typicode.com/users/1');
+ *         setDeleted(true);
+ *     };
+ *
+ *     return (
+ *         <Container>
+ *             <Button label="Delete User" onPress={deleteUser} />
+ *             {deleted && <Text>User deleted</Text>}
+ *         </Container>
+ *     );
+ * }
+ *
+ * @example
+ * // 6. GET with headers and params
+ * import { useEffect, useState } from 'react';
+ * import { Container, Text, httpGet } from 'fletbox';
+ *
+ * function ProfileScreen() {
+ *     const [profile, setProfile] = useState(null);
+ *
+ *     useEffect(() => {
+ *         async function loadProfile() {
+ *             const data = await httpGet('https://api.example.com/profile', {
+ *                 headers: { 'Authorization': 'Bearer token123' },
+ *                 params: { userId: 1 }
+ *             });
+ *             setProfile(data);
+ *         }
+ *         loadProfile();
+ *     }, []);
+ *
+ *     return (
+ *         <Container>
+ *             <Text>Name: {profile?.name}</Text>
+ *             <Text>Email: {profile?.email}</Text>
+ *         </Container>
+ *     );
+ * }
+ *
+ * @example
+ * // 7. Error handling
+ * import { useEffect, useState } from 'react';
+ * import { Container, Text, httpGet } from 'fletbox';
+ *
+ * function ErrorScreen() {
+ *     const [data, setData] = useState(null);
+ *     const [error, setError] = useState(null);
+ *
+ *     useEffect(() => {
+ *         async function loadData() {
+ *             try {
+ *                 const result = await httpGet('https://api.example.com/data');
+ *                 setData(result);
+ *             } catch (err) {
+ *                 setError(err.message);
+ *             }
+ *         }
+ *         loadData();
+ *     }, []);
+ *
+ *     return (
+ *         <Container>
+ *             {error && <Text color="red">Error: {error}</Text>}
+ *             {data && <Text>Data loaded</Text>}
+ *         </Container>
+ *     );
+ * }
+ *
+ * @example
+ * // 8. Loading state
+ * import { useEffect, useState } from 'react';
+ * import { Container, Text, ActivityIndicator, httpGet } from 'fletbox';
+ *
+ * function LoadingScreen() {
+ *     const [users, setUsers] = useState([]);
+ *     const [loading, setLoading] = useState(true);
+ *
+ *     useEffect(() => {
+ *         async function loadUsers() {
+ *             const data = await httpGet('https://jsonplaceholder.typicode.com/users');
+ *             setUsers(data);
+ *             setLoading(false);
+ *         }
+ *         loadUsers();
+ *     }, []);
+ *
+ *     return (
+ *         <Container>
+ *             {loading ? (
+ *                 <ActivityIndicator size="large" />
+ *             ) : (
+ *                 <Text>Users loaded: {users.length}</Text>
+ *             )}
+ *         </Container>
+ *     );
+ * }
+ *
+ * @example
+ * // 9. POST with loading
+ * import { useState } from 'react';
+ * import { Button, Container, Text, ActivityIndicator, httpPost } from 'fletbox';
+ *
+ * function SubmitScreen() {
+ *     const [loading, setLoading] = useState(false);
+ *     const [result, setResult] = useState(null);
+ *
+ *     const submit = async () => {
+ *         setLoading(true);
+ *         try {
+ *             const data = await httpPost('https://api.example.com/submit', {
+ *                 body: { message: 'Hello world' }
+ *             });
+ *             setResult(data);
+ *         } finally {
+ *             setLoading(false);
+ *         }
+ *     };
+ *
+ *     return (
+ *         <Container>
+ *             {loading ? (
+ *                 <ActivityIndicator size="large" />
+ *             ) : (
+ *                 <Button label="Submit" onPress={submit} />
+ *             )}
+ *             {result && <Text>Submitted: {result.id}</Text>}
+ *         </Container>
+ *     );
+ * }
+ *
+ * @example
+ * // 10. Custom timeout
+ * import { httpGet } from 'fletbox';
+ *
+ * async function slowRequest() {
+ *     try {
+ *         const data = await httpGet('https://api.lenta.com/datos', {
+ *             timeout: 5000  // 5 seconds max
+ *         });
+ *         console.log(data);
+ *     } catch (error) {
+ *         console.log('Timeout or error:', error.message);
+ *     }
+ * }
+ */
+
+async function httpRequest(method, url, options = {}) {
+  const { body, headers = {}, params = {}, timeout = 30000, ...rest } = options;
+
+  const queryString = new URLSearchParams(
+    Object.entries(params).filter(([, value]) => value !== null && value !== undefined),
+  ).toString();
+  const separator = url.includes("?") ? "&" : "?";
+  const finalUrl = queryString ? `${url}${separator}${queryString}` : url;
+
+  const config = {
+    method: method.toUpperCase(),
+    headers: {
+      "Content-Type": "application/json",
+      ...headers,
+    },
+    signal: AbortSignal.timeout(timeout),
+    ...rest,
+  };
+
+  if (body !== undefined) {
+    config.body = typeof body === "string" ? body : JSON.stringify(body);
+  }
+
+  try {
+    const response = await fetch(finalUrl, config);
+
+    let data;
+    const contentType = response.headers.get("content-type");
+    if (contentType?.includes("application/json")) {
+      data = await response.json();
+    } else {
+      data = await response.text();
+    }
+
+    if (!response.ok) {
+      const error = new Error(
+        `HTTP ${response.status}: ${response.statusText}`,
+      );
+      error.response = response;
+      error.data = data;
+      throw error;
+    }
+
+    return data;
+  } catch (error) {
+    if (error.name === "TimeoutError") {
+      throw new Error(`Request timeout after ${timeout}ms`);
+    }
+    throw error;
+  }
+}
+
+export async function httpGet(url, options = {}) {
+  return httpRequest("GET", url, options);
+}
+
+export async function httpPost(url, options = {}) {
+  return httpRequest("POST", url, options);
+}
+
+export async function httpPut(url, options = {}) {
+  return httpRequest("PUT", url, options);
+}
+
+export async function httpPatch(url, options = {}) {
+  return httpRequest("PATCH", url, options);
+}
+
+export async function httpDelete(url, options = {}) {
+  return httpRequest("DELETE", url, options);
+}
+
+export { httpRequest };

package/src/services/index.js

@@ -0,0 +1,57 @@
+// src/services/index.js
+export {
+  default as RamStore,
+  saveRam,
+  getRam,
+  getAllRam,
+  getAllRamKeys,
+  hasRam,
+  updateRam,
+  deleteRam,
+  clearAllRam,
+  subscribeRam,
+  getRamItemCount,
+  isRamAvailable,
+} from "./RamStore.js";
+export {
+  default as Session,
+  saveSession,
+  getSession,
+  getSessionSync,
+  updateSession,
+  deleteSession,
+  clearAllSession,
+  hasSession,
+  getAllSessionKeys,
+  getAllSessionData,
+  getSessionSize,
+  deleteSessionByPrefix,
+  deleteSessionBySuffix,
+  getSessionItemCount,
+  isSessionAvailable,
+} from "./Session.js";
+export {
+  default as Storage,
+  saveData,
+  getData,
+  getDataSync,
+  updateData,
+  deleteData,
+  clearAllData,
+  hasData,
+  getAllKeys,
+  getAllData,
+  getStorageSize,
+  deleteDataByPrefix,
+  deleteDataBySuffix,
+  getItemCount,
+  isStorageAvailable,
+} from "./Storage.js";
+export {
+  httpGet,
+  httpPost,
+  httpPut,
+  httpPatch,
+  httpDelete,
+  httpRequest,
+} from "./http.js";

package/src/tools/animation.js

@@ -0,0 +1,42 @@
+// tools/animation.js
+
+/**
+ * Generate CSS animation string
+ * @param {string|Object} name - Animation name or options object
+ * @param {number} duration - Duration in seconds
+ * @param {string} timing - Timing function
+ * @param {string} iteration - Iteration count
+ * @returns {string} CSS animation value
+ *
+ * @example
+ * animation('fadeIn', 0.5, 'ease-in-out', 'infinite')
+ * // "fadeIn 0.5s ease-in-out infinite"
+ *
+ * @example
+ * animation({ name: 'slideIn', duration: 0.3, timing: 'ease', delay: 0.1, fillMode: 'forwards' })
+ * // "slideIn 0.3s ease 0.1s forwards"
+ */
+export const animation = (
+  name,
+  duration = 0.3,
+  timing = "ease",
+  iteration = "1",
+) => {
+  if (typeof name === "object") {
+    const n = name.name;
+    const d = name.duration ?? 0.3;
+    const t = name.timing ?? "ease";
+    const dl = name.delay ?? 0;
+    const i = name.iteration ?? "1";
+    const dir = name.direction ?? "normal";
+    const fill = name.fillMode ?? "none";
+
+    let result = `${n} ${d}s ${t} ${dl}s ${i} ${dir}`;
+    if (fill !== "none") result += ` ${fill}`;
+    return result;
+  }
+
+  return `${name} ${duration}s ${timing} ${iteration}`;
+};
+
+export default animation;

package/src/tools/array.js

@@ -0,0 +1,95 @@
+// tools/array.js
+
+/**
+ * Shuffle an array (Fisher-Yates)
+ * @param {Array} arr - Input array
+ * @returns {Array} New shuffled array
+ * @example shuffle([1,2,3,4,5]) // [3,1,5,2,4]
+ */
+export const shuffle = (arr) => {
+  const result = [...arr];
+  for (let i = result.length - 1; i > 0; i--) {
+    const j = Math.floor(Math.random() * (i + 1));
+    [result[i], result[j]] = [result[j], result[i]];
+  }
+  return result;
+};
+
+/**
+ * Reverse an array
+ * @param {Array} arr - Input array
+ * @returns {Array} New reversed array
+ * @example reverse([1,2,3,4]) // [4,3,2,1]
+ */
+export const reverse = (arr) => {
+  return [...arr].reverse();
+};
+
+/**
+ * Sort array by key or custom function
+ * @param {Array} arr - Input array
+ * @param {string|Function} by - Key to sort by or sort function
+ * @param {string} order - 'asc' or 'desc' (default: 'asc')
+ * @returns {Array} New sorted array
+ * @example sort(users, 'name')
+ * @example sort(users, (a,b) => a.age - b.age)
+ */
+export const sort = (arr, by, order = "asc") => {
+  const result = [...arr];
+
+  if (typeof by === "function") {
+    result.sort(by);
+  } else if (typeof by === "string") {
+    result.sort((a, b) => {
+      const aVal = a[by];
+      const bVal = b[by];
+      if (typeof aVal === "number") {
+        return order === "asc" ? aVal - bVal : bVal - aVal;
+      }
+      const cmp = String(aVal).localeCompare(String(bVal));
+      return order === "asc" ? cmp : -cmp;
+    });
+  } else {
+    result.sort();
+  }
+
+  return order === "desc" && typeof by !== "function"
+    ? result.reverse()
+    : result;
+};
+
+/**
+ * Get unique values from array
+ * @param {Array} arr - Input array
+ * @param {string} key - Optional key for objects
+ * @returns {Array} Array with unique values
+ */
+export const unique = (arr, key = null) => {
+  if (key) {
+    const seen = new Set();
+    return arr.filter((item) => {
+      const value = item[key];
+      if (seen.has(value)) return false;
+      seen.add(value);
+      return true;
+    });
+  }
+  return [...new Set(arr)];
+};
+
+/**
+ * Chunk array into smaller arrays
+ * @param {Array} arr - Input array
+ * @param {number} size - Chunk size
+ * @returns {Array} Array of chunks
+ * @example chunk([1,2,3,4,5], 2) // [[1,2], [3,4], [5]]
+ */
+export const chunk = (arr, size) => {
+  const result = [];
+  for (let i = 0; i < arr.length; i += size) {
+    result.push(arr.slice(i, i + size));
+  }
+  return result;
+};
+
+export default { shuffle, reverse, sort, unique, chunk };

package/src/tools/border.js

@@ -0,0 +1,28 @@
+// tools/border.js
+
+/**
+ * Generate a CSS border shorthand string.
+ *
+ * Converts individual border parameters into the `border` CSS shorthand so
+ * callers don't have to concatenate strings manually. Accepts either a number
+ * (auto-suffixed with `"px"`) or a pre-formatted string for `width`.
+ *
+ * @param {number|string} [width=1] - Border width. Numbers are treated as pixels;
+ *   strings are used as-is (e.g. `"0.5rem"`, `"thin"`).
+ * @param {string} [style="solid"] - Border style — any valid CSS border-style keyword
+ *   (`"solid"`, `"dashed"`, `"dotted"`, `"double"`, `"none"`, etc.)
+ * @param {string} color - Border color — any valid CSS color value.
+ *   Required; there is no default because a colorless border is invisible.
+ * @returns {string} CSS border shorthand value
+ *
+ * @example
+ * border(1, 'solid', '#ccc')      // "1px solid #ccc"
+ * border(2, 'dashed', 'red')      // "2px dashed red"
+ * border('0.5rem', 'dotted', 'var(--outline)') // "0.5rem dotted var(--outline)"
+ */
+export const border = (width = 1, style = "solid", color) => {
+  const widthStr = typeof width === "number" ? `${width}px` : width;
+  return `${widthStr} ${style} ${color}`;
+};
+
+export default border;

package/src/tools/clipboard.js

@@ -0,0 +1,104 @@
+// src/components/flet-box/tools/clipboard.js
+
+/**
+ * Clipboard utility — provides a synchronous-feeling API for reading from and
+ * writing to the system clipboard.
+ *
+ * `copy` and `copyWithFeedback` are intentionally synchronous from the caller's
+ * perspective: the underlying async Clipboard API is handled internally so
+ * callers do not need to `await` them. `read` is genuinely async and must be
+ * awaited.
+ */
+export const clipboard = {
+  /**
+   * Copies text to the clipboard.
+   *
+   * Uses the modern async `navigator.clipboard.writeText` API when available,
+   * falling back to a hidden `<textarea>` + `execCommand("copy")` for older
+   * browsers. Errors from the async path are caught and silently rerouted to
+   * the fallback.
+   *
+   * @param {string} text - Text to copy.
+   * @returns {void}
+   */
+  copy: (text) => {
+    // Modern path — async internally but fire-and-forget for the caller
+    if (navigator.clipboard && navigator.clipboard.writeText) {
+      navigator.clipboard.writeText(text).catch((err) => {
+        console.error("Clipboard failed:", err);
+        clipboard._fallbackCopy(text);
+      });
+    } else {
+      // Fallback for browsers that do not support the Clipboard API
+      clipboard._fallbackCopy(text);
+    }
+  },
+
+  /**
+   * Legacy synchronous fallback that copies text using a hidden `<textarea>`
+   * and the deprecated `execCommand("copy")`.
+   *
+   * @private
+   * @param {string} text - Text to copy.
+   * @returns {void}
+   */
+  _fallbackCopy: (text) => {
+    const textarea = document.createElement("textarea");
+    textarea.value = text;
+    textarea.style.position = "fixed";
+    textarea.style.left = "-9999px";
+    textarea.style.top = "-9999px";
+    document.body.appendChild(textarea);
+    textarea.select();
+    document.execCommand("copy");
+    document.body.removeChild(textarea);
+  },
+
+  /**
+   * Copies text to the clipboard and briefly updates a DOM element to show
+   * visual confirmation (a checkmark for 1 second).
+   *
+   * @param {string} text - Text to copy.
+   * @param {HTMLElement} element - Element whose content is temporarily replaced
+   *   with a `"✓"` and whose background turns green as feedback.
+   * @returns {void}
+   */
+  copyWithFeedback: (text, element) => {
+    clipboard.copy(text);
+
+    if (element) {
+      const originalText = element.textContent;
+      const originalBg = element.style.backgroundColor;
+
+      element.textContent = "✓";
+      element.style.backgroundColor = "#27ae60";
+
+      setTimeout(() => {
+        element.textContent = originalText;
+        element.style.backgroundColor = originalBg;
+      }, 1000);
+    }
+  },
+
+  /**
+   * Reads the current text content of the clipboard.
+   *
+   * Unlike `copy`, this method IS async and must be awaited. It returns an
+   * empty string on failure (e.g. when permission is denied).
+   *
+   * @returns {Promise<string>} The clipboard text, or `""` on error.
+   *
+   * @example
+   * const text = await clipboard.read();
+   */
+  read: async () => {
+    try {
+      return await navigator.clipboard.readText();
+    } catch (error) {
+      console.error("Failed to read:", error);
+      return "";
+    }
+  },
+};
+
+export default clipboard;