@fringeworks/react-layouts 0.8.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mitsuhiro Seino
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.ja.md

@@ -0,0 +1,234 @@
+# @fringeworks/react-layouts
+
+`@fringeworks/react-layouts` は、CSSによる子要素のレイアウト制御に特化したニッチなライブラリです。\
+プロパティに応じたクラス名とCSS変数を自動的に設定するHOCを提供します。
+
+**[English README is available here](./README.md)**
+
+## インストール
+
+```bash
+npm install @fringeworks/react-layouts
+# または
+pnpm add @fringeworks/react-layouts
+```
+
+## 使い方
+
+任意のコンポーネントをHOCに渡すことで、レイアウト機能の適用されたコンポーネントを作成することができます。
+
+```ts
+import { withStackLayout } from '@fringeworks/react-layouts';
+
+// ※ classNameやstyle（CSS変数用）を透過するコンポーネントである必要があります
+const MyContainer = (props: React.ComponentProps<'div'>) => <div {...props} />;
+
+const StackContainer = withStackLayout(MyContainer);
+```
+
+```tsx
+<StackContainer>
+  <div>Item 1</div>
+  <div>Item 2</div>
+</StackContainer>
+```
+
+### CSSの読み込み
+
+HOCはCSSをインポートしないため、SSRやReact Server Componentsでもそのまま使用できます。CSSは別途インポートしてください。
+
+```ts
+import { withStackLayout } from '@fringeworks/react-layouts';
+
+// 全レイアウトをまとめてインポート
+import '@fringeworks/react-layouts/styles.css';
+
+// 必要なレイアウトのみインポート
+import '@fringeworks/react-layouts/stack.css';
+import '@fringeworks/react-layouts/tile.css';
+```
+
+CSSを自動的に読み込みたい場合は `with-css` 配下のモジュールを使用してください。CSSのインポートを扱えるバンドラーが必要です。
+
+```ts
+import { withStackLayout } from '@fringeworks/react-layouts/with-css';
+```
+
+## レイアウト種別
+
+### `stack`
+
+子要素を縦または横方向に一列に並べます。
+
+```tsx
+import { withStackLayout } from '@fringeworks/react-layouts';
+
+const StackContainer = withStackLayout(Container);
+
+// ----------------------
+
+<StackContainer
+  direction="x"
+  alignX="left"
+  alignY="top"
+  adjustX="grow"
+  itemSizeX="200px"
+  spacing="8px"
+/>;
+```
+
+### `flow`
+
+`stack`と同様ですが、コンテナサイズを超えた場合に子要素を折り返します。
+
+```tsx
+import { withFlowLayout } from '@fringeworks/react-layouts';
+
+const FlowContainer = withFlowLayout(Container);
+
+// ----------------------
+
+<FlowContainer
+  direction="x"
+  alignX="left"
+  alignY="top"
+  adjustX="grow"
+  itemSizeX="200px"
+  spacing="8px"
+/>;
+```
+
+> 交差軸方向の `adjust` に `grow`、`shrink`、`fit` は指定できません。
+
+### `matrix`
+
+列数・行数を指定して子要素を格子状に並べます。
+
+```tsx
+import { withMatrixLayout } from '@fringeworks/react-layouts';
+
+const MatrixContainer = withMatrixLayout(Container);
+
+// ----------------------
+
+<MatrixContainer
+  direction="x"
+  itemCountX={3}
+  childY={[200, 100, '1fr']}
+  itemSizeX="200px"
+  adjustX="fit"
+  spacing="8px"
+/>;
+```
+
+各軸で `itemCount` または `child` のどちらか一方が必須です（両方は指定不可）。
+
+> **注意:** このレイアウトはコンテナのサイズが外部から確定していることを前提としています。`width: max-content` など、子要素によってサイズが決まる親要素では、パーセンテージ値が意図通りに動作しない場合があります。
+
+### `tile`
+
+子要素のサイズを基準にして格子状に並べます。列数は親要素のサイズと子要素のサイズに応じて自動で決まります。
+
+```tsx
+import { withTileLayout } from '@fringeworks/react-layouts';
+
+const TileContainer = withTileLayout(Container);
+
+// ----------------------
+
+<TileContainer direction="x" itemSizeX="200px" adjustX="fit" spacing="8px" />;
+```
+
+> **注意:** `matrix` と同様に、コンテナのサイズが外部から確定していることを前提としています。
+
+### `balance`
+
+子要素を一列に均等に並べます。
+
+- `adjust` なし: 子要素のサイズを維持したまま、余白を均等に配分します
+- `adjust` あり: 子要素のサイズを調整してコンテナを満たします
+
+```tsx
+import { withBalanceLayout } from '@fringeworks/react-layouts';
+
+const BalanceContainer = withBalanceLayout(Container);
+
+// ----------------------
+
+<BalanceContainer
+  direction="x"
+  adjustX="grow"
+  itemSizeX="200px"
+  spacing="8px"
+/>;
+```
+
+### `pack`
+
+子要素を親要素のサイズに合わせて均等にサイズ調整し並べます。
+
+```tsx
+import { withPackLayout } from '@fringeworks/react-layouts';
+
+const PackContainer = withPackLayout(Container);
+
+// ----------------------
+
+<PackContainer direction="x" spacing="8px" />;
+```
+
+### `pin`
+
+子要素を指定の座標に配置します。子要素は `top` / `left` / `bottom` / `right` スタイルで位置を指定してください。
+
+```tsx
+import { withPinLayout } from '@fringeworks/react-layouts';
+
+const PinContainer = withPinLayout(Container);
+
+// ----------------------
+
+<PinContainer itemSizeX="100px" itemSizeY="80px" />;
+```
+
+## オプション
+
+### オプション一覧
+
+| オプション    | 型                       | 説明                         |
+| ------------- | ------------------------ | ---------------------------- |
+| `direction?`  | `'x' \| 'y'`             | 主軸の方向                   |
+| `alignX?`     | [`AlignX`](#alignx-の値) | 子要素の横位置               |
+| `alignY?`     | [`AlignY`](#aligny-の値) | 子要素の縦位置               |
+| `adjustX?`    | [`Adjust`](#adjust-の値) | 子要素の横方向のサイズ調整   |
+| `adjustY?`    | [`Adjust`](#adjust-の値) | 子要素の縦方向のサイズ調整   |
+| `spacing?`    | `string \| number`       | 子要素間の余白（横縦共通）   |
+| `spacingX?`   | `string \| number`       | 子要素間の余白（横方向）     |
+| `spacingY?`   | `string \| number`       | 子要素間の余白（縦方向）     |
+| `itemSizeX?`  | `string \| number`       | 子要素の幅                   |
+| `itemSizeY?`  | `string \| number`       | 子要素の高さ                 |
+| `itemCountX?` | `number`                 | 子要素の横方向の数           |
+| `itemCountY?` | `number`                 | 子要素の縦方向の数           |
+| `tracksX?`    | `(string \| number)[]`   | 子要素の横方向の個々のサイズ |
+| `tracksY?`    | `(string \| number)[]`   | 子要素の縦方向の個々のサイズ |
+
+### `Adjust` の値
+
+| 値       | 子が親より小さい時 | 子が親より大きい時 |
+| -------- | ------------------ | ------------------ |
+| `none`   | そのまま           | そのまま           |
+| `grow`   | 伸びる             | そのまま           |
+| `shrink` | そのまま           | 縮む               |
+| `fit`    | 伸びる             | 縮む               |
+
+### `AlignX` の値
+
+`'left'` | `'center'` | `'right'` | `'space-between'` | `'space-around'` | `'space-evenly'`
+
+### `AlignY` の値
+
+`'top'` | `'middle'` | `'bottom'` | `'space-between'` | `'space-around'` | `'space-evenly'`
+
+## ライセンス
+
+MIT

package/README.md

@@ -0,0 +1,236 @@
+# @fringeworks/react-layouts
+
+`@fringeworks/react-layouts` is a niche library tailored for controlling child element layouts via CSS.
+
+It provides Higher-Order Components (HOCs) that automatically apply class names and CSS variables based on the passed props.
+
+**[日本語のREADMEはこちら](./README.ja.md)**
+
+## Installation
+
+```bash
+npm install @fringeworks/react-layouts
+# or
+pnpm add @fringeworks/react-layouts
+
+```
+
+## Usage
+
+You can create a component with layout capabilities by passing any base component to the HOC.
+
+```tsx
+import { withStackLayout } from '@fringeworks/react-layouts';
+
+// * The wrapped component must pass down `className` and `style` (used for CSS variables) to its underlying element.
+const MyContainer = (props: React.ComponentProps<'div'>) => <div {...props} />;
+
+const StackContainer = withStackLayout(MyContainer);
+```
+
+```tsx
+<StackContainer>
+  <div>Item 1</div>
+  <div>Item 2</div>
+</StackContainer>
+```
+
+### Loading CSS
+
+The HOCs do not import any CSS, so they work as-is in SSR and React Server Components. Import the CSS separately.
+
+```ts
+import { withStackLayout } from '@fringeworks/react-layouts';
+
+// Import all layouts at once
+import '@fringeworks/react-layouts/styles.css';
+
+// Or import only what you need
+import '@fringeworks/react-layouts/stack.css';
+import '@fringeworks/react-layouts/tile.css';
+```
+
+If you want the CSS to be loaded automatically, use the modules under `with-css`. This requires a bundler that can handle CSS imports.
+
+```ts
+import { withStackLayout } from '@fringeworks/react-layouts/with-css';
+```
+
+## Layout Types
+
+### `stack`
+
+Arranges child elements in a single row or column (linear layout).
+
+```tsx
+import { withStackLayout } from '@fringeworks/react-layouts';
+
+const StackContainer = withStackLayout(Container);
+
+// ----------------------
+
+<StackContainer
+  direction="x"
+  alignX="left"
+  alignY="top"
+  adjustX="grow"
+  itemSizeX="200px"
+  spacing="8px"
+/>;
+```
+
+### `flow`
+
+Similar to `stack`, but wraps child elements onto multiple lines if they exceed the container size.
+
+```tsx
+import { withFlowLayout } from '@fringeworks/react-layouts';
+
+const FlowContainer = withFlowLayout(Container);
+
+// ----------------------
+
+<FlowContainer
+  direction="x"
+  alignX="left"
+  alignY="top"
+  adjustX="grow"
+  itemSizeX="200px"
+  spacing="8px"
+/>;
+```
+
+> `grow`, `shrink`, and `fit` cannot be specified for `adjust` on the cross-axis.
+
+### `matrix`
+
+Arranges child elements in a grid by specifying the number of columns and rows.
+
+```tsx
+import { withMatrixLayout } from '@fringeworks/react-layouts';
+
+const MatrixContainer = withMatrixLayout(Container);
+
+// ----------------------
+
+<MatrixContainer
+  direction="x"
+  itemCountX={3}
+  childY={[200, 100, '1fr']}
+  itemSizeX="200px"
+  adjustX="fit"
+  spacing="8px"
+/>;
+```
+
+For each axis, either `itemCount` or `child` is required (specifying both is not allowed).
+
+> **Note:** This layout assumes the container's size is determined externally. Percentage values may not work as intended in parent elements whose sizes are determined by their children (e.g., `width: max-content`).
+
+### `tile`
+
+Arranges child elements in a grid based on the child size. The number of columns is automatically calculated depending on the parent container's size and the child elements' sizes.
+
+```tsx
+import { withTileLayout } from '@fringeworks/react-layouts';
+
+const TileContainer = withTileLayout(Container);
+
+// ----------------------
+
+<TileContainer direction="x" itemSizeX="200px" adjustX="fit" spacing="8px" />;
+```
+
+> **Note:** Similar to `matrix`, this layout assumes the container's size is determined externally.
+
+### `balance`
+
+Distributes child elements evenly in a single row or column.
+
+- **Without `adjust`:** Maintains the original size of child elements and distributes the remaining space evenly.
+- **With `adjust`:** Adjusts the size of child elements to fill the container.
+
+```tsx
+import { withBalanceLayout } from '@fringeworks/react-layouts';
+
+const BalanceContainer = withBalanceLayout(Container);
+
+// ----------------------
+
+<BalanceContainer
+  direction="x"
+  adjustX="grow"
+  itemSizeX="200px"
+  spacing="8px"
+/>;
+```
+
+### `pack`
+
+Scales and packs child elements evenly to perfectly fit the size of the parent container.
+
+```tsx
+import { withPackLayout } from '@fringeworks/react-layouts';
+
+const PackContainer = withPackLayout(Container);
+
+// ----------------------
+
+<PackContainer direction="x" spacing="8px" />;
+```
+
+### `pin`
+
+Positions child elements at specific coordinates. Children should specify their positions using `top` / `left` / `bottom` / `right` styles.
+
+```tsx
+import { withPinLayout } from '@fringeworks/react-layouts';
+
+const PinContainer = withPinLayout(Container);
+
+// ----------------------
+
+<PinContainer itemSizeX="100px" itemSizeY="80px" />;
+```
+
+## Options
+
+### Option List
+
+| Option        | Type                   | Description                                               |
+| ------------- | ---------------------- | --------------------------------------------------------- |
+| `direction?`  | `'x' \| 'y'`           | Direction of the main axis                                |
+| `alignX?`     | [`AlignX`]()           | Horizontal alignment of child elements                    |
+| `alignY?`     | [`AlignY`]()           | Vertical alignment of child elements                      |
+| `adjustX?`    | [`Adjust`]()           | Horizontal size adjustment for child elements             |
+| `adjustY?`    | [`Adjust`]()           | Vertical size adjustment for child elements               |
+| `spacing?`    | `string \| number`     | Gap between child elements (both horizontal and vertical) |
+| `spacingX?`   | `string \| number`     | Horizontal gap between child elements                     |
+| `spacingY?`   | `string \| number`     | Vertical gap between child elements                       |
+| `itemSizeX?`  | `string \| number`     | Width of child elements                                   |
+| `itemSizeY?`  | `string \| number`     | Height of child elements                                  |
+| `itemCountX?` | `number`               | Number of child elements horizontally                     |
+| `itemCountY?` | `number`               | Number of child elements vertically                       |
+| `tracksX?`    | `(string \| number)[]` | Individual horizontal sizes for each child element        |
+| `tracksY?`    | `(string \| number)[]` | Individual vertical sizes for each child element          |
+
+### `Adjust` Values
+
+| Value    | When child is smaller than parent | When child is larger than parent |
+| -------- | --------------------------------- | -------------------------------- |
+| `none`   | Keeps original size               | Keeps original size              |
+| `grow`   | Expands                           | Keeps original size              |
+| `shrink` | Keeps original size               | Shrinks                          |
+| `fit`    | Expands                           | Shrinks                          |
+
+### `AlignX` Values
+
+`'left'` | `'center'` | `'right'` | `'space-between'` | `'space-around'` | `'space-evenly'`
+
+### `AlignY` Values
+
+`'top'` | `'middle'` | `'bottom'` | `'space-between'` | `'space-around'` | `'space-evenly'`
+
+## License
+
+MIT

package/_internal/_constants.cjs

@@ -0,0 +1,27 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: 'Module' });
+
+//#region src/_internal/_constants.ts
+const LAYOUT_PROPS_KEYS = {
+	className: 1,
+	scroll: 1,
+	style: 1,
+	direction: 1,
+	alignX: 1,
+	alignY: 1,
+	adjustX: 1,
+	adjustY: 1,
+	gap: 1,
+	gapX: 1,
+	gapY: 1,
+	itemSizeX: 1,
+	itemSizeY: 1,
+	itemRatioX: 1,
+	itemRatioY: 1,
+	itemCountX: 1,
+	itemCountY: 1,
+	tracksX: 1,
+	tracksY: 1
+};
+
+//#endregion
+exports.LAYOUT_PROPS_KEYS = LAYOUT_PROPS_KEYS;

package/_internal/_constants.d.cts

@@ -0,0 +1,7 @@
+import { ApplyLayoutOptions } from "./applyLayout/types.cjs";
+import { BalanceLayoutOptions, FlowLayoutOptions, MatrixLayoutOptions, PackLayoutOptions, PinLayoutOptions, StackLayoutOptions, TileLayoutOptions } from "@fringeworks/style-layouts";
+
+//#region src/_internal/_constants.d.ts
+declare const LAYOUT_PROPS_KEYS: { [K in keyof Required<ApplyLayoutOptions & BalanceLayoutOptions & FlowLayoutOptions & MatrixLayoutOptions & PackLayoutOptions & PinLayoutOptions & StackLayoutOptions & TileLayoutOptions>]: 1 };
+//#endregion
+export { LAYOUT_PROPS_KEYS };

package/_internal/_constants.d.mts

@@ -0,0 +1,7 @@
+import { ApplyLayoutOptions } from "./applyLayout/types.mjs";
+import { BalanceLayoutOptions, FlowLayoutOptions, MatrixLayoutOptions, PackLayoutOptions, PinLayoutOptions, StackLayoutOptions, TileLayoutOptions } from "@fringeworks/style-layouts";
+
+//#region src/_internal/_constants.d.ts
+declare const LAYOUT_PROPS_KEYS: { [K in keyof Required<ApplyLayoutOptions & BalanceLayoutOptions & FlowLayoutOptions & MatrixLayoutOptions & PackLayoutOptions & PinLayoutOptions & StackLayoutOptions & TileLayoutOptions>]: 1 };
+//#endregion
+export { LAYOUT_PROPS_KEYS };

package/_internal/_constants.mjs

@@ -0,0 +1,25 @@
+//#region src/_internal/_constants.ts
+const LAYOUT_PROPS_KEYS = {
+	className: 1,
+	scroll: 1,
+	style: 1,
+	direction: 1,
+	alignX: 1,
+	alignY: 1,
+	adjustX: 1,
+	adjustY: 1,
+	gap: 1,
+	gapX: 1,
+	gapY: 1,
+	itemSizeX: 1,
+	itemSizeY: 1,
+	itemRatioX: 1,
+	itemRatioY: 1,
+	itemCountX: 1,
+	itemCountY: 1,
+	tracksX: 1,
+	tracksY: 1
+};
+
+//#endregion
+export { LAYOUT_PROPS_KEYS };

package/_internal/applyLayout/applyLayout.cjs

@@ -0,0 +1,26 @@
+const require_runtime = require('../../_virtual/_rolldown/runtime.cjs');
+let _fringeworks_utils = require("@fringeworks/utils");
+let clsx = require("clsx");
+clsx = require_runtime.__toESM(clsx, 1);
+
+//#region src/_internal/applyLayout/applyLayout.ts
+/**
+* レイアウト用のスタイルを適用する
+* @param layout レイアウトを作る関数
+* @param options レイアウトのオプション
+* @returns
+*/
+function applyLayout(layout, options = (0, _fringeworks_utils.unsafeCast)({})) {
+	const { className, scroll, style: optionStyle, ...rest } = options;
+	const style = { ...optionStyle };
+	const { className: layoutedClassName, style: layoutedStyle } = layout((0, _fringeworks_utils.unsafeCast)(rest));
+	if (scroll) style.overflow = "auto";
+	if (layoutedStyle) Object.assign(style, layoutedStyle);
+	return {
+		className: (0, clsx.default)(className, layoutedClassName),
+		style
+	};
+}
+
+//#endregion
+module.exports = applyLayout;

package/_internal/applyLayout/applyLayout.d.cts

@@ -0,0 +1,13 @@
+import { ApplyLayoutOptions, ApplyLayoutResult } from "./types.cjs";
+import { CreateLayoutStyle } from "@fringeworks/style-layouts";
+import { LooseDictionary } from "@fringeworks/types";
+
+//#region src/_internal/applyLayout/applyLayout.d.ts
+/**
+ * レイアウト用のスタイルを適用する
+ * @param layout レイアウトを作る関数
+ * @param options レイアウトのオプション
+ * @returns
+ */
+declare function applyLayout<O extends object = LooseDictionary>(layout: CreateLayoutStyle<O>, options?: ApplyLayoutOptions<O>): ApplyLayoutResult;
+export = applyLayout;

package/_internal/applyLayout/applyLayout.d.mts

@@ -0,0 +1,14 @@
+import { ApplyLayoutOptions, ApplyLayoutResult } from "./types.mjs";
+import { CreateLayoutStyle } from "@fringeworks/style-layouts";
+import { LooseDictionary } from "@fringeworks/types";
+
+//#region src/_internal/applyLayout/applyLayout.d.ts
+/**
+ * レイアウト用のスタイルを適用する
+ * @param layout レイアウトを作る関数
+ * @param options レイアウトのオプション
+ * @returns
+ */
+declare function applyLayout<O extends object = LooseDictionary>(layout: CreateLayoutStyle<O>, options?: ApplyLayoutOptions<O>): ApplyLayoutResult;
+//#endregion
+export { applyLayout as default };

package/_internal/applyLayout/applyLayout.mjs

@@ -0,0 +1,24 @@
+import { unsafeCast } from "@fringeworks/utils";
+import clsx from "clsx";
+
+//#region src/_internal/applyLayout/applyLayout.ts
+/**
+* レイアウト用のスタイルを適用する
+* @param layout レイアウトを作る関数
+* @param options レイアウトのオプション
+* @returns
+*/
+function applyLayout(layout, options = unsafeCast({})) {
+	const { className, scroll, style: optionStyle, ...rest } = options;
+	const style = { ...optionStyle };
+	const { className: layoutedClassName, style: layoutedStyle } = layout(unsafeCast(rest));
+	if (scroll) style.overflow = "auto";
+	if (layoutedStyle) Object.assign(style, layoutedStyle);
+	return {
+		className: clsx(className, layoutedClassName),
+		style
+	};
+}
+
+//#endregion
+export { applyLayout as default };

package/_internal/applyLayout/index.cjs

@@ -0,0 +1,3 @@
+const require__internal_applyLayout_applyLayout = require('./applyLayout.cjs');
+
+module.exports = require__internal_applyLayout_applyLayout;

package/_internal/applyLayout/index.d.cts

@@ -0,0 +1,3 @@
+import { ApplyLayoutOptions, ApplyLayoutResult, LayoutBaseProps } from "./types.cjs";
+import applyLayout from "./applyLayout.cjs";
+export { type ApplyLayoutOptions, type ApplyLayoutResult, type LayoutBaseProps, applyLayout as default };

package/_internal/applyLayout/index.d.mts

@@ -0,0 +1,3 @@
+import { ApplyLayoutOptions, ApplyLayoutResult, LayoutBaseProps } from "./types.mjs";
+import applyLayout from "./applyLayout.mjs";
+export { type ApplyLayoutOptions, type ApplyLayoutResult, type LayoutBaseProps, applyLayout as default };

package/_internal/applyLayout/index.mjs

@@ -0,0 +1,3 @@
+import applyLayout from "./applyLayout.mjs";
+
+export { applyLayout as default };