Знакомимся с Cruzo. Часть 1. RxBucket – контейнер состояний и конфигураций компонентов на фронте / Хабр

Не так давно, я наконец выложил на github свой фреймворк cruzo – https://github.com/MaratBektemirov/cruzo. Сам фреймворк писался где-то с 2020г, в свободное от работы время. Причем большую часть времени я потратил на шаблонизатор с реактивными значениями.

Я сам в разработке с 2013 года, начинал с фронта. Еще когда не было angular.js, react - все сидели на jQuery, большая часть сайтов была не как single-page-application, а прям генерировалась на сервере. Первый мой фреймворк angularjs, поэтому он оказал сильное влияние на cruzo. Но я хотел сделать более минималистичный фреймворк, при этом чтобы все было: шаблонизатор, роутер, хтпп-клиент и чтобы он работал быстрее и весил меньше.

Я использовал LLM, по большей части для UI-тестов, примеров. Т.к. завершение фреймворка выпало на начало LLM-эры кодогенерации. ~80% кода написаны мной. Использовал также LLM для рутины в vm.ts с опкодами. Это сильно ускорило мою работу, ну я в принципе считаю, что LLM не способна решать на самом деле креативные задачи, ее удел, рутина в том или ином виде.

Я хотел сделать минималистичный, но в то же время мощный инструмент для создания простых и сложных веб-приложений. Попытался взять хорошие идеи от разных фреймворков и собрать их в одном месте. Одна из таких идей - это RxBucket - контейнер состояний (где-то это называют стором), я хотел оставить общую идею, но при этом, чтобы она выглядела минималистичной и функциональной.

import { AbstractComponent, componentsRegistryService, RxBucket } from "cruzo";
import { InputComponent, InputConfig } from "cruzo/ui-components/input";
import { ButtonGroupComponent, ButtonGroupConfig } from "cruzo/ui-components/button-group";

export class DemoRxBucketComponent extends AbstractComponent {
  static selector = "demo-rx-bucket-component";
  dependencies = new Set([InputComponent.selector, ButtonGroupComponent.selector]);

  innerBucket = new RxBucket({
    input: { config: InputConfig({ placeholder: "Enter your name" }) },
    buttonGroup: {
      config: ButtonGroupConfig({
        items: [
          { label: "Option A", value: "a" },
          { label: "Option B", value: "b" },
          { label: "Option C", value: "c" }
        ]
      })
    }
  });

  currentInputValue$ = this.newRxValueFromBucket(this.innerBucket, "input");
  currentButtonGroupValue$ = this.newRxValueFromBucket(this.innerBucket, "buttonGroup");

  constructor() {
    super();
  }

  getHTML() {
    return `<div>
        <div class="mb_m">
          <input-component
            component-id="input"
            bucket-id="${this.innerBucket.id}">
          </input-component>
        </div>

        <div class="mb_m">
          <button-group-component
            component-id="buttonGroup"
            bucket-id="${this.innerBucket.id}">
          </button-group-component>
        </div>

        <div class="mt_s">
          <div>Input value: <b>{{ root.currentInputValue$::rx }}</b></div>
          <div class="mt_xs">Selected: <b>{{ root.currentButtonGroupValue$::rx }}</b</div>
        </div>
      </div>`;
  }

  connectedCallback() {
    super.connectedCallback();
  }

}

componentsRegistryService.define(DemoRxBucketComponent);

В данном случае это внутренний бакет компонента (innerBucket). Бывают еще и внешние - outerBucket.

innerBucket - это бакет, который компонент создает внутри себя для своих дочерних компонентов. outerBucket - это бакет, который компонент получает снаружи через bucket-id. В примере выше, DemoRxBucketComponent создает innerBucket, а input-component и button-group-component уже работают с ним как с outerBucket.

Конфигурация компонентов

Можно задать конфигурацию для компонентов с определенным id. Вообще, спросите вы, почему конфигурация оказалась там? Ответ простой, очень часто: конфигурация, значение и состояние перемешаны друг с другом, и все при этом хранится в сторе, а здесь я разделил мух от котлет.

{ config: InputConfig({ placeholder: "Enter your name" }) }

Конфигурация выделяется в дескрипторе компонента свойством config. Значение и состояние не задаются изначально в дескрипторе, это сделано для более минималистичного API, да и очень часто на фронте значения задаются после получения данных из REST, поэтому на этапе конфигурации, мне кажется, в этом нет никакого смысла.

Например, значение можно задать уже после получения данных:

async connectedCallback() {
  super.connectedCallback();
  const profile = await this.getProfile();
  
  this.innerBucket.setValuesAtIndex({
    input: profile.name,
    buttonGroup: profile.type
  });
}

Стандартные реактивные значения AbstractComponent

Если мы говорим про значение (value$), это rx-свойство, сейчас вы увидите, как оно работает на уровне AbstractComponent cruzo:

export abstract class AbstractComponent<Config = any, ValueType = any, StateType = any> {
...
public value$ = this.newRx<ValueType>();
...
public connectedCallback(params: ComponentConnectedParams = null) {
  ...
  this.setValue();
  
  this.outerBucket.newRxValue(
    this.id,
    this.onUpdateValue,
    this.rxList,
    this.outerBucket.getValue(this.id, this.index),
    this.index
  );
  // Оно берется из outerBucket по id и index компонента.
}
...

Если описать поток данных коротко, то получается так: родительский компонент создает RxBucket, дочерний компонент получает bucket-id и component-id, находит свой outerBucket, берет из него config, value и state.

Вы легко можете использовать value$ через ::rx в шаблоне, в этом случае произойдет реактивная подписка.

getHTML() {
  return `<div class="${UI_KIT}_button-group">
    <button
      repeat="{{root.config$::rx.items}}"
      class="${UI_KIT}_button-group-item {{this.value === root.value$::rx ? '${UI_KIT}_button-group-item-active' : ''}}"
      onclick="{{root.select(this.value)}}"
    >
      {{this.label}}
    </button>
  </div>`
}

По этому же образу сделаны state$ и config$, они отделены умышленно, для логического разделения.

export abstract class AbstractComponent<Config = any, ValueType = any, StateType = any> {
...
public value$ = this.newRx<ValueType>();
...
public state$ = this.newRx<StateType>();
...
public config$ = this.newRx<Config>();
...

config$ - это конфигурация компонента, например: placeholder, type, items, required, name и другие настройки.

value$ - это текущее значение компонента: текст в input, выбранная кнопка в button-group, выбранный item в select и так далее.

state$ - это состояние компонента, которое не является значением. Например, css-класс, ошибка, disabled, loading, opened/closed и другие UI-состояния.

Например:

this.innerBucket.setState("input", { cls: "input-error" });

А внутри компонента это может использоваться так:

`class="${UI_KIT}_input {{root.state$::rx?.cls}}"`

Еще есть component-index. Он нужен, когда у вас несколько компонентов с одним component-id, например в repeat, списке или таблице. config при этом может быть один, а value и state будут храниться отдельно по index.

`<input-component
component-id="input"
component-index="0"
bucket-id="${this.innerBucket.id}">
</input-component>

<input-component
component-id="input"
component-index="1"
bucket-id="${this.innerBucket.id}">
</input-component>`

В таком случае это один descriptor input, но значения и состояния у компонентов будут разные.

Еще в RxBucket есть события. Они нужны, когда компоненту нужно не просто хранить value или state, а сообщить о каком-то действии: закрытие модалки, выбор, клик, изменение состояния роутер-ссылки и так далее.

bucket.emitEvent(id, name, bucketEvent, index)

Подписаться можно через:

this.newRxEventFromBucket(...)

или:

this.newRxEventFromBucketByIndex(...)

RxBucket пригодится там, где нужно связать несколько компонентов, не прокидывать props через несколько уровней и при этом не смешивать config, value и state в одну кашу.

В следующей части, возможно, разберем что-нибудь еще из Cruzo. Если, конечно, за это время меня не убедят, что весь фронтенд теперь должен состоять из одного промпта и трех AI-агентов... Ну а если хотите попробовать мой фреймворк https://github.com/MaratBektemirov/cruzo, я буду рад вашим звездам)