arekui 1.0.0

package/arekui.d.ts

@@ -0,0 +1,328 @@
+/**
+ * ARStyle v1.4.0
+ * A standalone CSS framework by Andika Rekatias.
+ *
+ * @example
+ * ```html
+ * <link rel="stylesheet" href="arstyle.css">
+ * <script src="arstyle.js"></script>
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // Set theme
+ * ARStyle.setTheme("dark");
+ *
+ * // Show toast
+ * ARStyle.toast("Saved!", { type: "success", duration: 4000 });
+ *
+ * // Get rating
+ * const rating = ARStyle.getRating(document.querySelector("[data-ar-rating]"));
+ * ```
+ */
+
+/** Available theme names */
+export type ThemeName = "light" | "dark" | "neo";
+
+/** Toast notification type */
+export type ToastType = "info" | "success" | "warning" | "error";
+
+/** Toast position on screen */
+export type ToastPosition =
+ | "top-left"
+ | "top-center"
+ | "top-right"
+ | "bottom-left"
+ | "bottom-center"
+ | "bottom-right";
+
+/** Options for toast notifications */
+export interface ToastOptions {
+ /** Toast type for styling */
+ type?: ToastType;
+
+ /** Auto-dismiss duration in milliseconds (0 = no auto-dismiss, default: 4000) */
+ duration?: number;
+
+ /** Toast position on screen (default: "top-right") */
+ position?: ToastPosition;
+
+ /** Show close button (default: true) */
+ closable?: boolean;
+
+ /** HTML icon content (displayed before message) */
+ icon?: string;
+}
+
+/** Options for creating custom events */
+export interface CustomEventOptions<T = unknown> {
+ /** Event detail payload */
+ detail: T;
+
+ /** Whether the event bubbles up the DOM (default: true) */
+ bubbles?: boolean;
+
+ /** Whether the event can be canceled (default: false) */
+ cancelable?: boolean;
+
+ /** Whether the event crosses shadow DOM boundaries (default: false) */
+ composed?: boolean;
+}
+
+/** Detail payload for ar-rating-change event */
+export interface RatingChangeDetail {
+ /** The selected rating value (0-5) */
+ value: number;
+}
+
+/** Detail payload for ar-file-change event */
+export interface FileChangeDetail {
+ /** The selected files */
+ files: FileList;
+}
+
+/**
+ * Custom event dispatched when rating changes
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent | CustomEvent}
+ */
+export interface RatingChangeEvent extends CustomEvent<RatingChangeDetail> {
+ type: "ar-rating-change";
+}
+
+/**
+ * Custom event dispatched when files are selected
+ * @see {@link https://developer.mozilla.org/en-US/docs/Web/API/CustomEvent | CustomEvent}
+ */
+export interface FileChangeEvent extends CustomEvent<FileChangeDetail> {
+ type: "ar-file-change";
+}
+
+/**
+ * ARStyle public API
+ *
+ * @description Provides theme management, toast notifications,
+ * rating controls, popover management, and initialization.
+ *
+ * @example
+ * ```html
+ * <script>
+ *   // Theme management
+ *   ARStyle.setTheme("neo");
+ *   console.log(ARStyle.getTheme()); // "neo"
+ *
+ *   // Toast notifications
+ *   ARStyle.toast("Item saved!", { type: "success" });
+ *
+ *   // Rating
+ *   const container = document.querySelector("[data-ar-rating]");
+ *   ARStyle.setRating(container, 4);
+ *   console.log(ARStyle.getRating(container)); // 4
+ *
+ *   // Popover
+ *   ARStyle.openPopover("my-popover");
+ * </script>
+ * ```
+ */
+export interface ARStyleStatic {
+ /**
+  * Set the active theme
+  *
+  * @param theme - The theme to activate
+  *
+  * @example
+  * ```typescript
+  * ARStyle.setTheme("dark");
+  * ARStyle.setTheme("neo");
+  * ```
+  */
+ setTheme(theme: ThemeName): void;
+
+ /**
+  * Get the currently active theme
+  *
+  * @returns The current theme name, or null if no theme is set
+  *
+  * @example
+  * ```typescript
+  * const current = ARStyle.getTheme();
+  * if (current === "dark") {
+  *   // Dark theme is active
+  * }
+  * ```
+  */
+ getTheme(): ThemeName | null;
+
+ /**
+  * Initialize theme from localStorage or system preference
+  *
+  * @description Checks localStorage for a saved theme, falls back to
+  * prefers-color-scheme media query, defaults to "light"
+  *
+  * @example
+  * ```typescript
+  * // Usually called automatically, but can be called manually
+  * ARStyle.initTheme();
+  * ```
+  */
+ initTheme(): void;
+
+ /**
+  * Initialize all ARStyle behaviors
+  *
+  * @description Sets up event listeners for theme toggle, modals, drawers,
+  * tabs, dropdowns, accordion, ratings, popovers, file uploads, and scroll-to-top
+  *
+  * @example
+  * ```typescript
+  * // Called automatically on DOMContentLoaded
+  * // Call manually if adding elements dynamically
+  * ARStyle.init();
+  * ```
+  */
+ init(): void;
+
+ /**
+  * Show a toast notification
+  *
+  * @param message - Toast message text
+  * @param options - Toast configuration options
+  * @returns The toast DOM element (can be used with dismissToast)
+  *
+  * @example
+  * ```typescript
+  * // Basic toast
+  * ARStyle.toast("Hello world!");
+  *
+  * // Success toast with custom duration
+  * ARStyle.toast("Saved successfully!", {
+  *   type: "success",
+  *   duration: 5000
+  * });
+  *
+  * // Persistent toast (no auto-dismiss)
+  * const loading = ARStyle.toast("Loading...", { duration: 0 });
+  *
+  * // Dismiss programmatically
+  * ARStyle.dismissToast(loading);
+  * ```
+  */
+ toast(message: string, options?: ToastOptions): HTMLElement;
+
+ /**
+  * Dismiss a toast element
+  *
+  * @param el - The toast element to dismiss
+  *
+  * @example
+  * ```typescript
+  * const toast = ARStyle.toast("Processing...");
+  * // ... later
+  * ARStyle.dismissToast(toast);
+  * ```
+  */
+ dismissToast(el: HTMLElement): void;
+
+ /**
+  * Get the current rating value from a rating container
+  *
+  * @param container - The rating container element (with data-ar-rating attribute)
+  * @returns The selected rating value (0-5), or 0 if nothing is selected
+  *
+  * @example
+  * ```typescript
+  * const container = document.querySelector("[data-ar-rating]");
+  * const rating = ARStyle.getRating(container);
+  * console.log(`Selected rating: ${rating}`);
+  * ```
+  */
+ getRating(container: HTMLElement): number;
+
+ /**
+  * Set rating programmatically
+  *
+  * @param container - The rating container element (with data-ar-rating attribute)
+  * @param value - Rating value (0-5)
+  *
+  * @example
+  * ```typescript
+  * const container = document.querySelector("[data-ar-rating]");
+  * ARStyle.setRating(container, 4); // Select 4 stars
+  * ```
+  */
+ setRating(container: HTMLElement, value: number): void;
+
+ /**
+  * Open a popover by ID
+  *
+  * @param id - The popover content element ID
+  *
+  * @example
+  * ```html
+  * <div class="ar-popover">
+  *   <button>Click me</button>
+  *   <div class="ar-popover-content" id="my-popover">
+  *     Popover content
+  *   </div>
+  * </div>
+  * ```
+  *
+  * ```typescript
+  * ARStyle.openPopover("my-popover");
+  * ```
+  */
+ openPopover(id: string): void;
+
+ /**
+  * Close a popover by ID
+  *
+  * @param id - The popover content element ID
+  *
+  * @example
+  * ```typescript
+  * ARStyle.closePopover("my-popover");
+  * ```
+  */
+ closePopover(id: string): void;
+}
+
+/**
+ * ARStyle global namespace
+ *
+ * @description Provides access to all ARStyle public methods
+ * when using the script tag approach (no module system)
+ *
+ * @see {@link ARStyleStatic} for method signatures and examples
+ */
+declare global {
+ interface Window {
+  /**
+   * ARStyle global API
+   *
+   * @example
+   * ```html
+   * <script src="arstyle.js"></script>
+   * <script>
+   *   ARStyle.setTheme("dark");
+   *   ARStyle.toast("Hello!");
+   * </script>
+   * ```
+   */
+  ARStyle: ARStyleStatic;
+ }
+}
+
+/**
+ * ARStyle module export
+ *
+ * @example
+ * ```typescript
+ * // ES Module import
+ * import ARStyle from "arstyle";
+ *
+ * ARStyle.setTheme("neo");
+ * ```
+ */
+declare const ARStyle: ARStyleStatic;
+
+export default ARStyle;
+export { ARStyle, ARStyleStatic };