TMA Frontend Framework

Легковесный фреймворк для одностраничных приложениях (SPA).

Описание

• Управление маршрутами на основе хэша ( #/path )
• Помошник в работе с Rest API: авторизация на основе jwt-токена; выполнение запросов (поддержка JSON и FormData)
• Функции для вызова кастомных алертов
• Компонент для ввода с автодополнением (DataDriverInput): загрузка данных, фильтрация, подсветка совпадений

Установка

Для установки через npm, выполните следующие команды:

npm install tma-frontend-framework  # Устанавливает основной фреймворк для маршрутизации
npm install --save-dev webpack css-loader style-loader webpack-cli  # Устанавливает инструменты для сборки проекта

Сборка приложения

Для сборки вашего приложения рекомендуется использовать сборщик, такой как Webpack. Вот пример конфигурации Webpack:

const path = require("path");

module.exports = {
    entry: "./app.js", // Точка входа для вашего кода
    output: {
        filename: "bundle.js",
        path: path.resolve(__dirname, "dist"),
    },
    mode: "development",
    resolve: {
        extensions: [".js", ".jsx", ".ts", ".tsx"], // Поддерживаемые расширения
    },
    module: {
        rules: [
            {
                test: /\.css$/,
                use: ['style-loader', 'css-loader'],
            },
        ],
    },
};

После сборки, не забудьте подключить сгенерированный бандл в вашем основном HTML файле:

<script src="./dist/bundle.js" defer></script>

Компоненты

Router

Router — это основная часть фреймворка для управления маршрутами. Подробное описание компонента Router и его возможностей доступно здесь.

Пример базовой настройки маршрутов:

import { Router } from "tma-frontend-framework";

const routes = {
    "/": () => console.log("Главная страница"),
    "/about": () => console.log("О проекте"),
    "/404": () => console.log("Страница не найдена"),
};

const router = new Router(routes);

ApiHelper

ApiHelper - это класс, который предоставляет методы для работы с API, включая авторизацию и выполнение запросов. Поддерживает как JSON, так и FormData запросы. Подробное описание класса доступно здесь.

Примеры использования:

Авторизация:

import { ApiHelper } from "tma-frontend-framework";

const apiHelper = new ApiHelper();

async function authenticate() {
    try {
        const token = await apiHelper.login('https://example.com/auth', 'username', 'password');
        console.log('Токен:', token);
    } catch (error) {
        console.error('Ошибка авторизации:', error);
    }
}

JSON запрос:

const response = await apiHelper.request('/api/data', 'POST', { 
  name: 'John', 
  email: '[email protected]' 
});

FormData запрос (загрузка файлов):

const formData = new FormData();
formData.append('file', fileInput.files[0]);
formData.append('userId', '123');

const response = await apiHelper.request('/api/upload', 'POST', formData);

DataDriverInput

Компонент для ввода данных с автодополнением и загрузкой данных. Подробное описание доступно в документации компонента.

Основные возможности:

• Загрузка данных через асинхронный загрузчик
• Фильтрация и подсветка совпадений
• Ограничение количества отображаемых элементов
• Валидация ввода

Базовый пример:

import { DataDriverInput } from "tma-frontend-framework";

const input = new DataDriverInput(
  {
    dataLoader: async () => {
      const response = await fetch('/api/data');
      return response.json();
    },
    inputId: 'city-input',
    labelText: 'Город'
  },
  200 // Максимальное количество подсказок
);

await input.initialize();
document.body.appendChild(input.container);

Ключевые параметры:

• options.dataLoader (Function) - Обязательная функция загрузки данных
• options.labelText (string) - Текст метки (по умолчанию '')
• options.inputPlaceholder (string) - Плейсхолдер (по умолчанию '')
• options.inputId (string) - ID поля ввода
• MAX_RESULTS (number) - Макс. количество подсказок (по умолчанию 300)

Алерты

Функции для управления алертами, включая создание и закрытие алертов. Подробное описание доступно здесь.

Пример использования:

import { showCustomAlert } from "tma-frontend-framework";

showCustomAlert('Заголовок', 'Сообщение');

Ограничения

• Поддерживаются только маршруты с хэшем (например, #/about).
• Поддерживаются параметры в маршрутах (например, /user/:id).

Обсуждения

У вас есть вопросы, идеи или предложения? Добро пожаловать в раздел Обсуждения!

Статус разработки

Проект активно разрабатывается. Мы будем рады вашему вкладу и предложениям!

Лицензия

Этот проект лицензирован под лицензией ISC.