@byndyusoft-ui/flex 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,108 @@
-# Temporary Holding Version
+# `@byndyusoft-ui/flex`
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+---
+
+> Flex-раскладка поверх `@byndyusoft-ui/view`: фабрика `createFlex` создаёт компонент
+> под набор значений отступов вашего проекта.
+
+## Установка
+
+```sh
+npm i @byndyusoft-ui/flex
+```
+
+## Фабрика createFlex (свои значения отступов)
+
+`createFlex` принимает компонент, созданный `createView` из `@byndyusoft-ui/view`, —
+значения `values` и их типы выводятся из него, отдельно передавать их не нужно.
+Изменили `values` в одном месте — типы и стили обоих компонентов обновились сами.
+
+```tsx
+// src/shared/ui/layout.ts
+import { createView } from '@byndyusoft-ui/view';
+import { createFlex } from '@byndyusoft-ui/flex';
+
+export const View = createView({
+    step: { value: 8, unit: 'px' },
+    values: { xs: 0.25, sm: 0.5, md: 1, lg: 1.5, xl: 2, xxl: 3 }
+} as const);
+
+export const Flex = createFlex(View);
+```
+
+```tsx
+import { Flex, View } from '@/shared/ui/layout';
+
+<Flex direction="column" gap="lg" p="xl">
+    <View mb="md">...</View>
+    <Flex gap="sm" alignItems="center">
+        ...
+    </Flex>
+</Flex>;
+```
+
+gap-пропсы принимают те же токены, что и spacing-пропсы View. Стили (классы отступов,
+gap и flex-модификаторы) генерируются автоматически и доставляются так же, как у
+`createView`: автоинъекция в браузере и компонент `ViewStylesInjector` для SSR — подробности
+в README `@byndyusoft-ui/view`. Шаг `step` фиксируется при создании фабрики, а gap и отступы
+выводятся готовыми CSS-длинами; дробные множители токенов поддерживаются. Flex наследует
+`prefix` созданного View (по умолчанию `bsui`), поэтому его классы используют тот же namespace.
+Flex поддерживает короткие aliases spacing-пропсов View
+(`m`, `mt`, `mh`, `p`, `pt`, `ph` и остальные); правила приоритета, aliases и сокращения
+классов описаны в README View.
+
+Чтобы использовать отдельный namespace, задайте `prefix` в `createView`; он автоматически
+применится и к классам Flex:
+
+```tsx
+const View = createView({
+    step: { value: 1, unit: 'rem' },
+    prefix: 'app',
+    values: { sm: 0.5, md: 1 }
+} as const);
+const Flex = createFlex(View); // классы app-flex, app-flex--g-md и т.п.
+```
+
+## Props
+
+| Проп                         | Тип                                                                                 | Описание                            |
+| ---------------------------- | ----------------------------------------------------------------------------------- | ----------------------------------- |
+| `direction`                  | `row \| row-reverse \| column \| column-reverse`                                    | `flex-direction`                    |
+| `wrap`                       | `nowrap \| wrap \| wrap-reverse`                                                    | `flex-wrap`                         |
+| `justifyContent`             | `flex-start \| flex-end \| center \| space-between \| space-around \| space-evenly` | `justify-content`                   |
+| `alignContent`               | варианты выше + `stretch`                                                           | `align-content`                     |
+| `alignItems`                 | `flex-start \| flex-end \| center \| baseline \| stretch`                           | `align-items`                       |
+| `gap`, `rowGap`, `columnGap` | токен `values`                                                                      | Отступы между элементами            |
+| spacing-пропсы View          | токен `values`                                                                      | Полные и короткие отступы           |
+| `ref`                        | `React.Ref<HTMLElement>`                                                            | Ref на host element созданного View |
+
+`ref` указывает на тот же HTMLElement, который рендерит созданный View, в том числе при
+переопределении тега через `as`:
+
+```tsx
+import { useRef } from 'react';
+
+const flexRef = useRef<HTMLElement>(null);
+<Flex as="section" ref={flexRef} gap="md">
+    ...
+</Flex>;
+```
+
+Остальные пропсы (`as`, `className`, нативные атрибуты) проксируются в созданный View.
+
+## Утилиты и типы
+
+Из точки входа пакета также доступны:
+
+-   `buildCss(config)` — генерация CSS для `gap`, `rowGap` и `columnGap`.
+-   `flexModifiersCss` — CSS базового класса и модификаторов раскладки.
+-   `blockClassName` — базовый класс `bsui-flex`.
+-   `getDirectionModifier`, `getWrapModifier`, `getAlignContentModifier`,
+    `getAlignItemsModifier`, `getJustifyContentModifier` — имена классов модификаторов;
+    без аргумента возвращают пустую строку.
+-   `directions`, `flexWraps`, `alignContentVariants`, `alignItemsVariants`,
+    `justifyContentVariants` — наборы допустимых значений, например для элементов управления.
+
+Публичные типы: `ICreatedFlex`, `ICreatedFlexProps`, `TFlexDirection`, `TFlexWrap`,
+`TAlignContent`, `TAlignItems` и `TJustifyContent`. Созданный компонент имеет
+`displayName = 'Flex'` и хранит конфигурацию View в `Flex.config`.

package/dist/constants.d.ts

@@ -0,0 +1,9 @@
+export declare const blockClassName = "bsui-flex";
+export declare function getFlexBlockClassName(classPrefix?: string): string;
+export declare const directions: readonly ["row", "column", "row-reverse", "column-reverse"];
+export declare const flexWraps: readonly ["nowrap", "wrap", "wrap-reverse"];
+export declare const justifyContentVariants: readonly ["flex-start", "flex-end", "center", "space-between", "space-around", "space-evenly"];
+export declare const alignContentVariants: readonly ["flex-start", "flex-end", "center", "space-between", "space-around", "space-evenly", "stretch"];
+export declare const alignItemsVariants: readonly ["flex-start", "flex-end", "center", "baseline", "stretch"];
+export declare function buildFlexModifiersCss(classPrefix?: string): string;
+export declare const flexModifiersCss: string;

package/dist/constants.js

@@ -0,0 +1,58 @@
+const blockClassName = 'bsui-flex';
+function getFlexBlockClassName(classPrefix = 'bsui') {
+    return `${classPrefix}-flex`;
+}
+const directions = ['row', 'column', 'row-reverse', 'column-reverse'];
+const flexWraps = ['nowrap', 'wrap', 'wrap-reverse'];
+const justifyContentVariants = [
+    'flex-start',
+    'flex-end',
+    'center',
+    'space-between',
+    'space-around',
+    'space-evenly'
+];
+const alignContentVariants = [
+    'flex-start',
+    'flex-end',
+    'center',
+    'space-between',
+    'space-around',
+    'space-evenly',
+    'stretch'
+];
+const alignItemsVariants = ['flex-start', 'flex-end', 'center', 'baseline', 'stretch'];
+function buildFlexModifiersCss(classPrefix = 'bsui') {
+    const flexClassName = getFlexBlockClassName(classPrefix);
+    return [
+        `.${flexClassName}{display:flex}`,
+        `.${flexClassName}--fd-row{flex-direction:row}`,
+        `.${flexClassName}--fd-row-reverse{flex-direction:row-reverse}`,
+        `.${flexClassName}--fd-column{flex-direction:column}`,
+        `.${flexClassName}--fd-column-reverse{flex-direction:column-reverse}`,
+        `.${flexClassName}--fw-nowrap{flex-wrap:nowrap}`,
+        `.${flexClassName}--fw-wrap{flex-wrap:wrap}`,
+        `.${flexClassName}--fw-wrap-reverse{flex-wrap:wrap-reverse}`,
+        `.${flexClassName}--jc-flex-start{justify-content:flex-start}`,
+        `.${flexClassName}--jc-flex-end{justify-content:flex-end}`,
+        `.${flexClassName}--jc-center{justify-content:center}`,
+        `.${flexClassName}--jc-space-between{justify-content:space-between}`,
+        `.${flexClassName}--jc-space-around{justify-content:space-around}`,
+        `.${flexClassName}--jc-space-evenly{justify-content:space-evenly}`,
+        `.${flexClassName}--ac-flex-start{align-content:flex-start}`,
+        `.${flexClassName}--ac-flex-end{align-content:flex-end}`,
+        `.${flexClassName}--ac-center{align-content:center}`,
+        `.${flexClassName}--ac-space-between{align-content:space-between}`,
+        `.${flexClassName}--ac-space-around{align-content:space-around}`,
+        `.${flexClassName}--ac-space-evenly{align-content:space-evenly}`,
+        `.${flexClassName}--ac-stretch{align-content:stretch}`,
+        `.${flexClassName}--ai-flex-start{align-items:flex-start}`,
+        `.${flexClassName}--ai-flex-end{align-items:flex-end}`,
+        `.${flexClassName}--ai-center{align-items:center}`,
+        `.${flexClassName}--ai-baseline{align-items:baseline}`,
+        `.${flexClassName}--ai-stretch{align-items:stretch}`
+    ].join('');
+}
+const flexModifiersCss = buildFlexModifiersCss();
+
+export { alignContentVariants, alignItemsVariants, blockClassName, buildFlexModifiersCss, directions, flexModifiersCss, flexWraps, getFlexBlockClassName, justifyContentVariants };

package/dist/createFlex.d.ts

@@ -0,0 +1,3 @@
+import { type ICreatedView, type TSpacingValues } from '@byndyusoft-ui/view';
+import type { ICreatedFlex } from './types';
+export declare function createFlex<TValues extends TSpacingValues>(view: ICreatedView<TValues>): ICreatedFlex<TValues>;

package/dist/createFlex.js

@@ -0,0 +1,24 @@
+import React, { forwardRef } from 'react';
+import cn from 'classnames';
+import { registerStyles } from '@byndyusoft-ui/view';
+import { buildFlexModifiersCss, getFlexBlockClassName } from './constants.js';
+import { buildCss } from './utilities/buildCss.js';
+import { getAlignContentModifier } from './utilities/getAlignContentModifier.js';
+import { getAlignItemsModifier } from './utilities/getAlignItemsModifier.js';
+import { getDirectionModifier } from './utilities/getDirectionModifier.js';
+import { getGapClassNames } from './utilities/getGapClassNames.js';
+import { getJustifyContentModifier } from './utilities/getJustifyContentModifier.js';
+import { getWrapModifier } from './utilities/getWrapModifier.js';
+
+function createFlex(view) {
+    const classPrefix = view.config.prefix;
+    registerStyles(view.config, buildFlexModifiersCss(classPrefix) + buildCss(view.config));
+    const CreatedFlex = forwardRef(({ className, children, direction, wrap, alignContent, alignItems, justifyContent, gap, rowGap, columnGap, ...props }, ref) => {
+        const flexClassName = cn(getFlexBlockClassName(classPrefix), className, getDirectionModifier(direction, classPrefix), getWrapModifier(wrap, classPrefix), getAlignContentModifier(alignContent, classPrefix), getAlignItemsModifier(alignItems, classPrefix), getJustifyContentModifier(justifyContent, classPrefix), ...getGapClassNames(gap, rowGap, columnGap, classPrefix));
+        return React.createElement(view, { className: flexClassName, ...props, ref }, children);
+    });
+    CreatedFlex.displayName = 'Flex';
+    return Object.assign(CreatedFlex, { config: view.config });
+}
+
+export { createFlex };

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { createFlex } from './createFlex';
+export { alignContentVariants, alignItemsVariants, blockClassName, directions, flexModifiersCss, flexWraps, justifyContentVariants } from './constants';
+export { buildCss, getAlignContentModifier, getAlignItemsModifier, getDirectionModifier, getJustifyContentModifier, getWrapModifier } from './utilities';
+export type { ICreatedFlex, ICreatedFlexProps, TAlignContent, TAlignItems, TFlexDirection, TFlexWrap, TJustifyContent } from './types';

package/dist/index.js

@@ -0,0 +1,8 @@
+export { createFlex } from './createFlex.js';
+export { alignContentVariants, alignItemsVariants, blockClassName, directions, flexModifiersCss, flexWraps, justifyContentVariants } from './constants.js';
+export { buildCss } from './utilities/buildCss.js';
+export { getAlignContentModifier } from './utilities/getAlignContentModifier.js';
+export { getAlignItemsModifier } from './utilities/getAlignItemsModifier.js';
+export { getDirectionModifier } from './utilities/getDirectionModifier.js';
+export { getJustifyContentModifier } from './utilities/getJustifyContentModifier.js';
+export { getWrapModifier } from './utilities/getWrapModifier.js';

package/dist/types.d.ts

@@ -0,0 +1,21 @@
+import type { ForwardRefExoticComponent, RefAttributes } from 'react';
+import type { ICreatedViewProps, IViewConfig, TSpacingValues, TValuesToken } from '@byndyusoft-ui/view';
+import type { alignContentVariants, alignItemsVariants, directions, flexWraps, justifyContentVariants } from './constants';
+export type TFlexDirection = (typeof directions)[number];
+export type TFlexWrap = (typeof flexWraps)[number];
+export type TJustifyContent = (typeof justifyContentVariants)[number];
+export type TAlignContent = (typeof alignContentVariants)[number];
+export type TAlignItems = (typeof alignItemsVariants)[number];
+export interface ICreatedFlexProps<TValues extends TSpacingValues> extends ICreatedViewProps<TValues> {
+    alignContent?: TAlignContent;
+    alignItems?: TAlignItems;
+    direction?: TFlexDirection;
+    justifyContent?: TJustifyContent;
+    wrap?: TFlexWrap;
+    gap?: TValuesToken<TValues>;
+    rowGap?: TValuesToken<TValues>;
+    columnGap?: TValuesToken<TValues>;
+}
+export interface ICreatedFlex<TValues extends TSpacingValues> extends ForwardRefExoticComponent<ICreatedFlexProps<TValues> & RefAttributes<HTMLElement>> {
+    readonly config: IViewConfig<TValues>;
+}

package/dist/utilities/buildCss.d.ts

@@ -0,0 +1,2 @@
+import { type IViewConfig, type TSpacingValues } from '@byndyusoft-ui/view';
+export declare function buildCss<TValues extends TSpacingValues>(config: IViewConfig<TValues>): string;

package/dist/utilities/buildCss.js

@@ -0,0 +1,15 @@
+import { getSpacingValue } from '@byndyusoft-ui/view';
+
+function buildCss(config) {
+    const rules = [];
+    const blockClassName = `${config.prefix ?? 'bsui'}-flex`;
+    Object.entries(config.values).forEach(([token, multiplier]) => {
+        const value = getSpacingValue(config.step, multiplier);
+        rules.push(`.${blockClassName}--g-${token}{gap:${value}}`);
+        rules.push(`.${blockClassName}--rg-${token}{row-gap:${value}}`);
+        rules.push(`.${blockClassName}--cg-${token}{column-gap:${value}}`);
+    });
+    return rules.join('');
+}
+
+export { buildCss };

package/dist/utilities/getAlignContentModifier.d.ts

@@ -0,0 +1,2 @@
+import type { TAlignContent } from '../types';
+export declare function getAlignContentModifier(alignContent?: TAlignContent, classPrefix?: string): string;

package/dist/utilities/getAlignContentModifier.js

@@ -0,0 +1,7 @@
+import { getFlexBlockClassName } from '../constants.js';
+
+function getAlignContentModifier(alignContent, classPrefix = 'bsui') {
+    return alignContent ? `${getFlexBlockClassName(classPrefix)}--ac-${alignContent}` : '';
+}
+
+export { getAlignContentModifier };

package/dist/utilities/getAlignItemsModifier.d.ts

@@ -0,0 +1,2 @@
+import type { TAlignItems } from '../types';
+export declare function getAlignItemsModifier(alignItems?: TAlignItems, classPrefix?: string): string;

package/dist/utilities/getAlignItemsModifier.js

@@ -0,0 +1,7 @@
+import { getFlexBlockClassName } from '../constants.js';
+
+function getAlignItemsModifier(alignItems, classPrefix = 'bsui') {
+    return alignItems ? `${getFlexBlockClassName(classPrefix)}--ai-${alignItems}` : '';
+}
+
+export { getAlignItemsModifier };

package/dist/utilities/getDirectionModifier.d.ts

@@ -0,0 +1,2 @@
+import type { TFlexDirection } from '../types';
+export declare function getDirectionModifier(direction?: TFlexDirection, classPrefix?: string): string;

package/dist/utilities/getDirectionModifier.js

@@ -0,0 +1,7 @@
+import { getFlexBlockClassName } from '../constants.js';
+
+function getDirectionModifier(direction, classPrefix = 'bsui') {
+    return direction ? `${getFlexBlockClassName(classPrefix)}--fd-${direction}` : '';
+}
+
+export { getDirectionModifier };

package/dist/utilities/getGapClassNames.d.ts

@@ -0,0 +1 @@
+export declare function getGapClassNames(gap?: string, rowGap?: string, columnGap?: string, classPrefix?: string): Array<string>;

package/dist/utilities/getGapClassNames.js

@@ -0,0 +1,19 @@
+function getGapClassNames(gap, rowGap, columnGap, classPrefix = 'bsui') {
+    const blockClassName = `${classPrefix}-flex`;
+    if (gap) {
+        return [`${blockClassName}--g-${gap}`];
+    }
+    if (rowGap === columnGap && columnGap !== undefined) {
+        return [`${blockClassName}--g-${columnGap}`];
+    }
+    const classNames = [];
+    if (rowGap) {
+        classNames.push(`${blockClassName}--rg-${rowGap}`);
+    }
+    if (columnGap) {
+        classNames.push(`${blockClassName}--cg-${columnGap}`);
+    }
+    return classNames;
+}
+
+export { getGapClassNames };

package/dist/utilities/getJustifyContentModifier.d.ts

@@ -0,0 +1,2 @@
+import type { TJustifyContent } from '../types';
+export declare function getJustifyContentModifier(justifyContent?: TJustifyContent, classPrefix?: string): string;

package/dist/utilities/getJustifyContentModifier.js

@@ -0,0 +1,7 @@
+import { getFlexBlockClassName } from '../constants.js';
+
+function getJustifyContentModifier(justifyContent, classPrefix = 'bsui') {
+    return justifyContent ? `${getFlexBlockClassName(classPrefix)}--jc-${justifyContent}` : '';
+}
+
+export { getJustifyContentModifier };

package/dist/utilities/getWrapModifier.d.ts

@@ -0,0 +1,2 @@
+import type { TFlexWrap } from '../types';
+export declare function getWrapModifier(wrap?: TFlexWrap, classPrefix?: string): string;

package/dist/utilities/getWrapModifier.js

@@ -0,0 +1,7 @@
+import { getFlexBlockClassName } from '../constants.js';
+
+function getWrapModifier(wrap, classPrefix = 'bsui') {
+    return wrap ? `${getFlexBlockClassName(classPrefix)}--fw-${wrap}` : '';
+}
+
+export { getWrapModifier };

package/dist/utilities/index.d.ts

@@ -0,0 +1,7 @@
+export { buildCss } from './buildCss';
+export { getAlignContentModifier } from './getAlignContentModifier';
+export { getAlignItemsModifier } from './getAlignItemsModifier';
+export { getDirectionModifier } from './getDirectionModifier';
+export { getGapClassNames } from './getGapClassNames';
+export { getJustifyContentModifier } from './getJustifyContentModifier';
+export { getWrapModifier } from './getWrapModifier';

package/package.json

@@ -1,6 +1,49 @@
 {
   "name": "@byndyusoft-ui/flex",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "Byndyusoft UI Flex React Component",
+  "keywords": [
+    "byndyusoft",
+    "byndyusoft-ui",
+    "react",
+    "flex"
+  ],
+  "author": "Byndyusoft Frontend Developer <frontend@byndyusoft.com>",
+  "homepage": "https://github.com/Byndyusoft/ui/tree/master/components/flex#readme",
+  "license": "Apache-2.0",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist/**/*"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Byndyusoft/ui.git"
+  },
+  "scripts": {
+    "build": "rollup --config",
+    "clean": "rimraf dist && rimraf .turbo && rimraf node_modules && rimraf package-lock.json",
+    "lint:check": "npm run eslint:check && npm run prettier:check && npm run stylelint:check",
+    "lint:fix": "npm run eslint:fix && npm run prettier:fix && npm run stylelint:fix",
+    "eslint:check": "eslint src --config ../../eslint.config.js",
+    "eslint:fix": "eslint src --config ../../eslint.config.js --fix",
+    "prettier:check": "prettier --check \"**/*.{ts,tsx,css,scss,json}\"",
+    "prettier:fix": "prettier --write \"**/*.{ts,tsx,css,scss,json}\"",
+    "stylelint:check": "stylelint '**/*.{css,scss}' --allow-empty-input",
+    "stylelint:fix": "stylelint '**/*.{css,scss}' --fix --allow-empty-input",
+    "test": "vitest run --typecheck --root ../.. --exclude '**/.delta/**' components/flex/src"
+  },
+  "bugs": {
+    "url": "https://github.com/Byndyusoft/ui/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": ">=17"
+  },
+  "dependencies": {
+    "@byndyusoft-ui/view": "^1.0.1",
+    "classnames": "^2.3.1"
+  }
+}