softable-pixels-web 1.0.0

package/dist/index-jFi4YRO5.d.ts

@@ -0,0 +1,277 @@
+import { PropsWithChildren } from "react";
+
+//#region src/utils/functions/deepMerge.d.ts
+/** biome-ignore-all lint/suspicious/noExplicitAny: <Not needed> */
+type DeepPartial<T> = { [P in keyof T]?: T[P] extends Array<infer U> ? Array<DeepPartial<U>> : T[P] extends object ? DeepPartial<T[P]> : T[P] };
+//#endregion
+//#region src/contexts/ThemeContext/types.d.ts
+/**
+ * ThemeName
+ * ---------
+ * A theme identifier string.
+ *
+ * Examples:
+ * - "light"
+ * - "dark"
+ * - "dev"
+ * - "prod"
+ * - "brandA"
+ */
+type ThemeName = string;
+/**
+ * ThemeMode
+ * ---------
+ * The value users can select at runtime.
+ *
+ * - `"system"`: resolves automatically to `"light"` or `"dark"` using
+ *   the OS/browser preference (`prefers-color-scheme`).
+ * - any other string: treated as a concrete theme name.
+ *
+ * Examples:
+ * - "system" (default)
+ * - "light"
+ * - "dark"
+ * - "dev"
+ */
+type ThemeMode = 'system' | ThemeName;
+/**
+ * ThemeTokens
+ * ----------
+ * The fully-resolved theme object used by the component library.
+ *
+ * IMPORTANT:
+ * - Inside the library, components should assume `ThemeTokens` is complete.
+ * - Consumers are allowed to pass partial theme objects (DeepPartial), but the
+ *   ThemeProvider MUST merge them on top of a complete base theme (light/dark defaults),
+ *   ensuring the final `theme` is always safe to read at runtime.
+ *
+ * Design principles:
+ * - Keep tokens semantic (primary/surface/text/border) rather than raw palette names.
+ * - Provide neutral tokens (background/surface/border/text) + semantic intents (success/warning/etc).
+ * - Keep the structure stable; adding tokens is non-breaking, removing is breaking.
+ */
+interface ThemeTokens {
+  /**
+   * Color tokens.
+   *
+   * Suggested usage:
+   * - `primary`: brand accent color (buttons, highlights)
+   * - `secondary`: secondary text or subtle accents
+   * - intents (`success`, `warning`, `error`, `info`): feedback states
+   * - `background`: main page background
+   * - `surface`: elevated surface (cards, panels)
+   * - `border`: borders/dividers
+   * - `text`: primary/secondary/disabled/inverse text colors
+   */
+  colors: {
+    /** Main brand/accent color */
+    primary: string;
+    /** Secondary accent or subtle text color */
+    secondary: string;
+    /** Semantic colors (feedback) */
+    success: string;
+    warning: string;
+    error: string;
+    info: string;
+    /** Neutral surfaces */
+    background: string;
+    surface: string;
+    /** Border colors */
+    border: {
+      /** Primary border/divider color */
+      primary: string;
+      /** Secondary border color (less prominent) */
+      secondary: string;
+    };
+    /** Text colors */
+    text: {
+      /** Primary text color */
+      primary: string;
+      /** Secondary text color (muted) */
+      secondary: string;
+      /** Disabled text color */
+      disabled: string;
+      /** Text color to use on top of strong backgrounds (e.g. primary buttons) */
+      inverse: string;
+    };
+  };
+  /**
+   * Spacing scale (in px numbers, usually converted to `px` in styles).
+   * Keeps spacing consistent across components.
+   */
+  spacing: Record<'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl', number>;
+  /**
+   * Border radius scale (in px numbers).
+   */
+  borderRadius: Record<'none' | 'sm' | 'md' | 'lg' | 'full', number>;
+  /**
+   * Font size scale (in px numbers).
+   */
+  fontSize: Record<'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl', number>;
+  /**
+   * Font weight scale (numeric values).
+   */
+  fontWeight: Record<'normal' | 'medium' | 'semibold' | 'bold', number>;
+  /**
+   * Shadow tokens (CSS shadow strings).
+   */
+  shadows: Record<'sm' | 'md' | 'lg' | 'xl', string>;
+  /**
+   * Extension point.
+   *
+   * Allows consumers to add custom tokens without type errors.
+   * The library should avoid relying on unknown keys unless explicitly supported.
+   */
+  [key: string]: any;
+}
+/**
+ * ThemeRegistry
+ * -------------
+ * A registry of theme entries by name.
+ *
+ * Rules:
+ * - `light` and `dark` must always exist.
+ * - Each entry can be:
+ *   - a full `ThemeTokens`, OR
+ *   - a `DeepPartial<ThemeTokens>` patch (recommended)
+ *
+ * Why allow DeepPartial?
+ * - Consumers typically want to override only a few tokens, like `colors.primary`,
+ *   without having to redefine the entire token set.
+ *
+ * IMPORTANT:
+ * - Registry entries should be treated as patches by the ThemeProvider.
+ * - The ThemeProvider should always merge patches on top of a complete base theme
+ *   (usually the library's default light/dark tokens) to guarantee runtime safety.
+ */
+type ThemeRegistry = {
+  light: DeepPartial<ThemeTokens> | ThemeTokens;
+  dark: DeepPartial<ThemeTokens> | ThemeTokens;
+} & Record<string, DeepPartial<ThemeTokens> | ThemeTokens>;
+/**
+ * ThemeContextData
+ * ---------------
+ * The runtime API exposed by `useTheme()`.
+ *
+ * Fields:
+ * - `mode`: the selected mode ("system" or a theme name)
+ * - `resolvedName`: the actual applied theme name (never "system")
+ * - `theme`: the resolved theme tokens (should always be complete)
+ * - `isLoading`: provider initialization flag
+ *
+ * Methods:
+ * - `setTheme(mode)`: sets the selected theme mode
+ * - `toggleTheme(a?, b?)`: toggles between two theme names (defaults to light/dark)
+ */
+type ThemeContextData = {
+  /** Selected mode (a theme name or "system") */
+  mode: ThemeMode;
+  /** Resolved theme name (never "system") */
+  resolvedName: ThemeName;
+  /** Fully resolved tokens (should be complete) */
+  theme: ThemeTokens;
+  /** True while provider initializes (first render) */
+  isLoading: boolean;
+  /**
+   * Sets the selected theme mode.
+   *
+   * Examples:
+   * - setTheme("system")
+   * - setTheme("light")
+   * - setTheme("dark")
+   * - setTheme("dev")
+   */
+  setTheme: (mode: ThemeMode) => void;
+  /**
+   * Toggles between two theme names (defaults to "light" and "dark").
+   *
+   * Examples:
+   * - toggleTheme() // light <-> dark
+   * - toggleTheme("dev", "prod") // dev <-> prod
+   */
+  toggleTheme: (a?: ThemeName, b?: ThemeName) => void;
+};
+/**
+ * Theme Persistence Adapter
+ * ------------------------
+ * Optional persistence layer for the selected `mode`.
+ *
+ * Rules:
+ * - Persist the *selected* `mode` (including `"system"`), not the resolvedName.
+ * - `get()` can return null/undefined when nothing is stored.
+ */
+type ThemePersistence = {
+  /** Read the saved mode. Return null/undefined when absent. */
+  get: () => ThemeMode | null | undefined;
+  /** Persist the mode. */
+  set: (mode: ThemeMode) => void;
+  /** Optional: clear persistence (reset). */
+  clear?: () => void;
+};
+/**
+ * Props for ThemeProvider.
+ */
+type ThemeProviderProps = PropsWithChildren & {
+  /**
+   * Optional theme registry overrides.
+   *
+   * - The library ships with built-in `light` and `dark` themes (always complete).
+   * - You can override them partially (patch).
+   * - You can add additional named themes (e.g. `dev`, `prod`, `brandA`).
+   */
+  themes?: Partial<ThemeRegistry>;
+  /**
+   * Initial selected mode.
+   *
+   * - `"system"` (default): resolves to `"light"` or `"dark"` based on OS settings.
+   * - Any string theme name: resolves directly to that theme name.
+   */
+  defaultMode?: ThemeMode;
+  /**
+   * Optional final patch applied on top of the resolved theme.
+   * Useful for temporary/section-level overrides without defining a whole new theme.
+   */
+  override?: Partial<ThemeTokens>;
+  /**
+   * Quick persistence toggle (localStorage).
+   *
+   * When `true` and `persistence` is NOT provided, ThemeProvider will:
+   * - restore initial mode from `localStorage.getItem(storageKey)`
+   * - persist mode changes to `localStorage.setItem(storageKey, mode)`
+   *
+   * Default: false
+   */
+  persist?: boolean;
+  /**
+   * Storage key used when `persist` is enabled (localStorage mode).
+   *
+   * Default: "px-theme"
+   */
+  storageKey?: string;
+  /**
+   * Advanced persistence adapter.
+   *
+   * When provided, it takes priority over `persist`.
+   * Allows persistence via cookies, server, indexedDB, etc.
+   */
+  persistence?: ThemePersistence;
+};
+//#endregion
+//#region src/contexts/ThemeContext/index.d.ts
+/**
+ * ThemeProvider
+ * -------------
+ * Provides theme state + resolved theme tokens to your app.
+ */
+declare const ThemeProvider: React.FC<ThemeProviderProps>;
+/**
+ * useTheme()
+ *
+ * Returns the current theme context.
+ *
+ * @throws If called outside of `<ThemeProvider />`.
+ */
+declare function useTheme(): ThemeContextData;
+//#endregion
+export { ThemeName as a, ThemeRegistry as c, ThemeMode as i, ThemeTokens as l, useTheme as n, ThemePersistence as o, ThemeContextData as r, ThemeProviderProps as s, ThemeProvider as t };
+//# sourceMappingURL=index-jFi4YRO5.d.ts.map

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+import { n as SwitchOption, r as TabSwitchProps, t as TabSwitch } from "./index-CZOu4S--.js";
+import { a as ThemeName, c as ThemeRegistry, i as ThemeMode, l as ThemeTokens, n as useTheme, o as ThemePersistence, r as ThemeContextData, s as ThemeProviderProps, t as ThemeProvider } from "./index-jFi4YRO5.js";
+export { SwitchOption, TabSwitch, TabSwitchProps, ThemeContextData, ThemeMode, ThemeName, ThemePersistence, ThemeProvider, ThemeProviderProps, ThemeRegistry, ThemeTokens, useTheme };

package/dist/index.js

@@ -0,0 +1,4 @@
+import { t as TabSwitch } from "./TabSwitch-D6OPAUjC.js";
+import { n as useTheme, t as ThemeProvider } from "./ThemeContext-CRXby8a0.js";
+
+export { TabSwitch, ThemeProvider, useTheme };

package/dist/mask-modules.d.ts

@@ -0,0 +1,144 @@
+//#region src/services/MaskModule/enums.d.ts
+/**
+ * Supported locales (country + language region).
+ *
+ * Extend this enum as needed for new countries.
+ */
+declare enum Locale {
+  BR = "pt-BR",
+  // Brazil
+  US = "en-US",
+  // United States
+  AR = "es-AR",
+}
+/**
+ * Types of masks supported in the system.
+ *
+ * Add new types as needed for different data formats.
+ */
+declare enum MaskType {
+  CPF = "CPF",
+  CNPJ = "CNPJ",
+  DOCUMENT = "DOCUMENT",
+  PHONE = "PHONE",
+  DATE = "DATE",
+  FLOAT = "FLOAT",
+  INTEGER = "INTEGER",
+  MONEY = "MONEY",
+  ZIP_CODE = "ZIP_CODE",
+  NUMERIC_SYMBOL = "NUMERIC_SYMBOL",
+}
+//#endregion
+//#region src/services/MaskModule/types.d.ts
+/**
+ * Represents a generic mask.
+ *
+ * A mask is responsible for formatting and unformatting (removing formatting) from a value.
+ */
+interface Mask {
+  /**
+   * Optional minimum length of the masked string.
+   */
+  minLength?: number;
+  /**
+   * Optional maximum length of the masked string.
+   */
+  maxLength?: number;
+  /**
+   * Formats a plain string into a masked format.
+   * @param value - Raw string (e.g., "12345678901").
+   * @returns Masked string (e.g., "123.456.789-01").
+   */
+  format(value: string): string;
+  /**
+   * Removes all mask characters from a formatted string.
+   * @param value - Masked string (e.g., "123.456.789-01").
+   * @returns Unmasked string (e.g., "12345678901").
+   */
+  unmask(value: string): string;
+}
+/**
+ * Represents a validator for a masked value.
+ *
+ * A validator checks whether a masked value is valid based on rules.
+ */
+interface Validator {
+  /**
+   * Validates whether the input value is valid.
+   * @param value - Masked string.
+   * @returns `true` if valid, `false` otherwise.
+   */
+  validate(value: string): boolean;
+}
+//#endregion
+//#region src/services/MaskModule/base/BaseMask.d.ts
+/**
+ * Abstract class that provides default behavior for most masks.
+ * - Implements unmask() by removing all non-numeric characters.
+ * - Supports optional maxLength and minLength constraints.
+ */
+declare abstract class BaseMask implements Mask {
+  /**
+   * Maximum length of the masked string (optional).
+   */
+  maxLength?: number;
+  /**
+   * Minimum length of the masked string (optional).
+   */
+  minLength?: number;
+  constructor(minLength?: number, maxLength?: number);
+  /**
+   * Removes all non-numeric characters from a string.
+   * @param value - Masked or unmasked string.
+   * @returns Plain string with digits only.
+   */
+  unmask(value: string): string;
+  /**
+   * Must be implemented by each concrete mask class.
+   * Applies the mask format to the input string.
+   * @param value - Raw string.
+   * @returns Masked string.
+   */
+  abstract format(value: string): string;
+}
+//#endregion
+//#region src/services/MaskModule/base/BaseValidator.d.ts
+/**
+ * Abstract class providing common validation utilities.
+ * - Supports regex validation.
+ * - Supports min and max length validation.
+ */
+declare abstract class BaseValidator implements Validator {
+  protected pattern?: RegExp;
+  protected minLength?: number;
+  protected maxLength?: number;
+  constructor(options?: {
+    pattern?: RegExp;
+    minLength?: number;
+    maxLength?: number;
+  });
+  /**
+   * Validates the input value based on:
+   * - Pattern matching (if defined)
+   * - Min length (if defined)
+   * - Max length (if defined)
+   *
+   * Override this method if you need custom validation logic.
+   *
+   * @param value - Value to validate (usually masked string)
+   * @returns true if valid, false otherwise
+   */
+  validate(value: string): boolean;
+}
+//#endregion
+//#region src/services/MaskModule/MaskModule.d.ts
+declare const MaskModule: {
+  registerMask(locale: Locale, type: MaskType, mask: BaseMask): void;
+  registerValidator(locale: Locale, type: MaskType, validator: BaseValidator): void;
+  getMask(locale: Locale, type: MaskType): BaseMask | undefined;
+  getValidator(locale: Locale, type: MaskType): BaseValidator | undefined;
+  reset(): void;
+};
+//#endregion
+export { Locale, MaskModule, MaskType };
+//# sourceMappingURL=mask-modules.d.ts.map