@niche-works/css-layouts 0.1.0 → 0.2.0

package/README.ja.md

@@ -0,0 +1,240 @@
+# @niche-works/css-layouts
+
+`@niche-works/css-layouts` は、CSSによる子要素のレイアウト制御に特化したニッチなライブラリです。\
+オプションに応じたクラス名とCSS変数をオブジェクトとして返します。フレームワーク非依存でSSRにも対応しています。
+
+**[English README is available here](./README.md)**
+
+## 特徴
+
+- フレームワーク非依存（あらゆるJS環境で動作）
+- SSR対応（クラス名とインラインスタイルオブジェクトを返すだけ）
+- TypeScriptによる完全な型サポート
+
+## インストール
+
+```bash
+npm install @niche-works/css-layouts
+# または
+pnpm add @niche-works/css-layouts
+```
+
+## 使い方
+
+各レイアウト関数は `{ className, style }` オブジェクトを返します。コンテナ要素に適用してください。
+
+```ts
+import { stack } from '@niche-works/css-layouts';
+
+const { className, style } = stack({
+  direction: 'x',
+  alignX: 'center',
+  alignY: 'middle',
+  spacing: '16px',
+});
+
+// className: "nws-layout-stack nws-layout-direction-x ..."
+// style: { "--nws-layout-spacingX": "16px", ... }
+```
+
+```html
+<div class="nws-layout-stack ..." style="--nws-layout-spacingX: 16px; ...">
+  <div>Item 1</div>
+  <div>Item 2</div>
+</div>
+```
+
+> **注意:** ライブラリのCSSを別途インポートしてください。
+
+```ts
+// 全レイアウトをまとめてインポート
+import '@niche-works/css-layouts/styles.css';
+
+// 必要なレイアウトのみインポート
+import '@niche-works/css-layouts/stack.css';
+import '@niche-works/css-layouts/tile.css';
+```
+
+## レイアウト種別
+
+### `stack`
+
+子要素を縦または横方向に一列に並べます。
+
+```ts
+import { stack } from '@niche-works/css-layouts';
+
+const { className, style } = stack({
+  direction: 'x', // 'x' | 'y' — デフォルト: 'x'
+  alignX: 'left', // 'left' | 'center' | 'right'
+  alignY: 'top', // 'top' | 'middle' | 'bottom'
+  adjustX: 'grow', // 'none' | 'grow' | 'shrink' | 'fit'
+  childSizeX: '200px',
+  spacing: '8px',
+});
+```
+
+### `flow`
+
+`stack`と同様ですが、コンテナサイズを超えた場合に子要素を折り返します。
+
+```ts
+import { flow } from '@niche-works/css-layouts';
+
+const { className, style } = flow({
+  direction: 'x',
+  alignX: 'left',
+  alignY: 'top',
+  adjustX: 'fit',
+  childSizeX: '200px',
+  spacing: '8px',
+});
+```
+
+> 交差軸方向の `adjust` に `grow`、`shrink`、`fit` は指定できません。
+
+### `matrix`
+
+列数・行数を指定して子要素を格子状に並べます。
+
+```ts
+import { matrix } from '@niche-works/css-layouts';
+
+const { className, style } = matrix({
+  direction: 'x',
+  childCountX: 3, // 必須（または childX）
+  childCountY: 2, // 必須（または childY）
+  childSizeX: '200px',
+  adjustX: 'fit',
+  spacing: '8px',
+});
+```
+
+各軸で `childCountX` または `childX` のどちらか一方が必須です（両方は指定不可）。
+
+```ts
+// グリッドトラックを直接指定する場合
+matrix({
+  childX: ['1fr', '2fr', '1fr'],
+  childCountY: 3,
+});
+```
+
+> **注意:** このレイアウトはコンテナのサイズが外部から確定していることを前提としています。`width: max-content` など、子要素によってサイズが決まる親要素では、パーセンテージ値が意図通りに動作しない場合があります。
+
+### `tile`
+
+子要素のサイズを基準にして格子状に並べます。列数は親要素のサイズと子要素のサイズに応じて自動で決まります。
+
+```ts
+import { tile } from '@niche-works/css-layouts';
+
+const { className, style } = tile({
+  direction: 'x',
+  childSizeX: '200px',
+  adjustX: 'fit',
+  spacing: '8px',
+});
+```
+
+> **注意:** `matrix` と同様に、コンテナのサイズが外部から確定していることを前提としています。
+
+### `balance`
+
+子要素を一列に均等に並べます。
+
+- `adjust` なし: 子要素のサイズを維持したまま、余白を均等に配分します
+- `adjust` あり: 子要素のサイズを調整してコンテナを満たします
+
+```ts
+import { balance } from '@niche-works/css-layouts';
+
+const { className, style } = balance({
+  direction: 'x',
+  adjustX: 'grow',
+  childSizeX: '200px',
+  spacing: '8px',
+});
+```
+
+### `pack`
+
+子要素を親要素のサイズに合わせて均等にサイズ調整し並べます。
+
+```ts
+import { pack } from '@niche-works/css-layouts';
+
+const { className, style } = pack({
+  direction: 'x', // 'x' | 'y' — デフォルト: 'x'
+  spacing: '8px',
+});
+```
+
+### `pin`
+
+子要素を指定の座標に配置します。子要素は `top` / `left` / `bottom` / `right` スタイルで位置を指定してください。
+
+```ts
+import { pin } from '@niche-works/css-layouts';
+
+const { className, style } = pin({
+  childSizeX: '100px',
+  childSizeY: '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`       | 子要素間の余白（縦方向）     |
+| `childSizeX`  | `string \| number`       | 子要素の幅                   |
+| `childSizeY`  | `string \| number`       | 子要素の高さ                 |
+| `childCountX` | `string \| number`       | 子要素の横方向の数           |
+| `childCountY` | `string \| number`       | 子要素の縦方向の数           |
+| `childX`      | `(string \| number)[]`   | 子要素の横方向の個々のサイズ |
+| `childY`      | `(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'`
+
+## 戻り値
+
+全てのレイアウト関数は `LayoutResult` を返します。
+
+```ts
+type LayoutResult = {
+  className?: string;
+  style?: {
+    [key: string]: string | number | undefined;
+    [key: `--${string}`]: string | number | undefined;
+  };
+};
+```
+
+## ライセンス
+
+MIT

package/README.md

@@ -1,3 +1,240 @@
 # @niche-works/css-layouts
 
-A niche library for adding layout features using CSS.
+`@niche-works/css-layouts` is a niche library specialized in controlling child element layout with CSS.
+It returns class names and CSS custom properties as an object based on the given options. Framework-agnostic and SSR-compatible.
+
+**[日本語のREADMEはこちら](./README.ja.md)**
+
+## Features
+
+- Framework-agnostic (works with any JS environment)
+- SSR-compatible (returns plain class names and inline style objects)
+- Fully typed with TypeScript
+
+## Installation
+
+```bash
+npm install @niche-works/css-layouts
+# or
+pnpm add @niche-works/css-layouts
+```
+
+## Usage
+
+Each layout function returns a `{ className, style }` object. Apply them to a container element.
+
+```ts
+import { stack } from '@niche-works/css-layouts';
+
+const { className, style } = stack({
+  direction: 'x',
+  alignX: 'center',
+  alignY: 'middle',
+  spacing: '16px',
+});
+
+// className: "nws-layout-stack nws-layout-direction-x ..."
+// style: { "--nws-layout-spacingX": "16px", ... }
+```
+
+```html
+<div class="nws-layout-stack ..." style="--nws-layout-spacingX: 16px; ...">
+  <div>Item 1</div>
+  <div>Item 2</div>
+</div>
+```
+
+> **Note:** You need to import the CSS separately.
+
+```ts
+// Import all layouts at once
+import '@niche-works/css-layouts/styles.css';
+
+// Or import only what you need
+import '@niche-works/css-layouts/stack.css';
+import '@niche-works/css-layouts/tile.css';
+```
+
+## Layout Types
+
+### `stack`
+
+Arranges child elements in a single row or column.
+
+```ts
+import { stack } from '@niche-works/css-layouts';
+
+const { className, style } = stack({
+  direction: 'x', // 'x' | 'y' — default: 'x'
+  alignX: 'left', // 'left' | 'center' | 'right'
+  alignY: 'top', // 'top' | 'middle' | 'bottom'
+  adjustX: 'grow', // 'none' | 'grow' | 'shrink' | 'fit'
+  childSizeX: '200px',
+  spacing: '8px',
+});
+```
+
+### `flow`
+
+Like `stack`, but wraps child elements when they exceed the container size.
+
+```ts
+import { flow } from '@niche-works/css-layouts';
+
+const { className, style } = flow({
+  direction: 'x',
+  alignX: 'left',
+  alignY: 'top',
+  adjustX: 'fit',
+  childSizeX: '200px',
+  spacing: '8px',
+});
+```
+
+> `grow`, `shrink`, and `fit` cannot be specified for `adjust` on the cross axis.
+
+### `matrix`
+
+Arranges child elements in a grid with explicit column and row counts.
+
+```ts
+import { matrix } from '@niche-works/css-layouts';
+
+const { className, style } = matrix({
+  direction: 'x',
+  childCountX: 3, // required (or childX)
+  childCountY: 2, // required (or childY)
+  childSizeX: '200px',
+  adjustX: 'fit',
+  spacing: '8px',
+});
+```
+
+Either `childCountX` or `childX` is required per axis (not both).
+
+```ts
+// Using explicit track templates
+matrix({
+  childX: ['1fr', '2fr', '1fr'],
+  childCountY: 3,
+});
+```
+
+> **Note:** This layout assumes the container size is determined externally. Containers sized by their own content (e.g. `width: max-content`) may cause unexpected behavior with percentage-based values.
+
+### `tile`
+
+Arranges child elements in a grid based on child element size. The number of columns is determined automatically based on the container and child sizes.
+
+```ts
+import { tile } from '@niche-works/css-layouts';
+
+const { className, style } = tile({
+  direction: 'x',
+  childSizeX: '200px',
+  adjustX: 'fit',
+  spacing: '8px',
+});
+```
+
+> **Note:** Like `matrix`, this layout assumes the container size is determined externally.
+
+### `balance`
+
+Arranges child elements evenly in a single row or column.
+
+- Without `adjust`: maintains child size and distributes space evenly between items
+- With `adjust`: adjusts child size to fill the container evenly
+
+```ts
+import { balance } from '@niche-works/css-layouts';
+
+const { className, style } = balance({
+  direction: 'x',
+  adjustX: 'grow',
+  childSizeX: '200px',
+  spacing: '8px',
+});
+```
+
+### `pack`
+
+Sizes child elements equally to fill the container.
+
+```ts
+import { pack } from '@niche-works/css-layouts';
+
+const { className, style } = pack({
+  direction: 'x', // 'x' | 'y' — default: 'x'
+  spacing: '8px',
+});
+```
+
+### `pin`
+
+Positions child elements at specified coordinates. Each child element should have its position set via `top` / `left` / `bottom` / `right` styles.
+
+```ts
+import { pin } from '@niche-works/css-layouts';
+
+const { className, style } = pin({
+  childSizeX: '100px',
+  childSizeY: '80px',
+});
+```
+
+## Options
+
+### Options Reference
+
+| Option        | Type                       | Description                                |
+| ------------- | -------------------------- | ------------------------------------------ |
+| `direction`   | `'x' \| 'y'`               | Main axis direction                        |
+| `alignX`      | [`AlignX`](#alignx-values) | Horizontal alignment of children           |
+| `alignY`      | [`AlignY`](#aligny-values) | Vertical alignment of children             |
+| `adjustX`     | [`Adjust`](#adjust-values) | Horizontal size adjustment of children     |
+| `adjustY`     | [`Adjust`](#adjust-values) | Vertical size adjustment of children       |
+| `spacing`     | `string \| number`         | Gap between children (both axes)           |
+| `spacingX`    | `string \| number`         | Gap between children (horizontal)          |
+| `spacingY`    | `string \| number`         | Gap between children (vertical)            |
+| `childSizeX`  | `string \| number`         | Width of child elements                    |
+| `childSizeY`  | `string \| number`         | Height of child elements                   |
+| `childCountX` | `number`                   | Number of children in horizontal direction |
+| `childCountY` | `number`                   | Number of children in vertical direction   |
+| `childX`      | `(string \| number)[]`     | Individual sizes of children (horizontal)  |
+| `childY`      | `(string \| number)[]`     | Individual sizes of children (vertical)    |
+
+### `Adjust` Values
+
+| Value    | Child smaller than parent | Child larger than parent |
+| -------- | ------------------------- | ------------------------ |
+| `none`   | No change                 | No change                |
+| `grow`   | Grows to fill             | No change                |
+| `shrink` | No change                 | Shrinks to fit           |
+| `fit`    | Grows to fill             | Shrinks to fit           |
+
+### `AlignX` Values
+
+`'left'` | `'center'` | `'right'` | `'space-between'` | `'space-around'` | `'space-evenly'`
+
+### `AlignY` Values
+
+`'top'` | `'middle'` | `'bottom'` | `'space-between'` | `'space-around'` | `'space-evenly'`
+
+## Return Value
+
+All layout functions return a `LayoutResult`:
+
+```ts
+type LayoutResult = {
+  className?: string;
+  style?: {
+    [key: string]: string | number | undefined;
+    [key: `--${string}`]: string | number | undefined;
+  };
+};
+```
+
+## License
+
+MIT

package/balance/balance.cjs

@@ -3,7 +3,6 @@ const require_constants = require('../constants.cjs');
 const require__constants = require('../_constants.cjs');
 const require__helpers_applyChildSize = require('../_helpers/applyChildSize.cjs');
 const require__helpers_applySpacing = require('../_helpers/applySpacing.cjs');
-require('./styles.cjs');
 let _niche_works_utils_object_maybeDefault = require("@niche-works/utils/object/maybeDefault");
 _niche_works_utils_object_maybeDefault = require_runtime.__toESM(_niche_works_utils_object_maybeDefault, 1);
 let clsx = require("clsx");

package/balance/balance.mjs

@@ -2,7 +2,6 @@ import { clsLayoutBalance } from "../constants.mjs";
 import { clsLayoutAdjust, clsLayoutAlign, clsLayoutDirection } from "../_constants.mjs";
 import applyChildSize from "../_helpers/applyChildSize.mjs";
 import applySpacing from "../_helpers/applySpacing.mjs";
-import "./styles.css";
 import maybeDefault from "@niche-works/utils/object/maybeDefault";
 import clsx from "clsx";
 

package/balance/balance.scss.cjs

@@ -0,0 +1 @@
+require('./balance.cjs');

package/balance/balance.scss.d.cts

@@ -0,0 +1 @@
+export { };

package/balance/balance.scss.d.mts

@@ -0,0 +1 @@
+export { };

package/balance/balance.scss.mjs

@@ -0,0 +1,3 @@
+/* empty css         */
+
+export {  };

package/flow/flow.cjs

@@ -5,7 +5,6 @@ const require__helpers_hasValue = require('../_helpers/hasValue.cjs');
 const require__helpers_unit = require('../_helpers/unit.cjs');
 const require__helpers_applySpacing = require('../_helpers/applySpacing.cjs');
 const require__helpers_mergeLayoutResults = require('../_helpers/mergeLayoutResults.cjs');
-require('./styles.cjs');
 let _niche_works_utils_object_maybeDefault = require("@niche-works/utils/object/maybeDefault");
 _niche_works_utils_object_maybeDefault = require_runtime.__toESM(_niche_works_utils_object_maybeDefault, 1);
 let clsx = require("clsx");

package/flow/flow.mjs

@@ -4,7 +4,6 @@ import hasValue from "../_helpers/hasValue.mjs";
 import unit from "../_helpers/unit.mjs";
 import applySpacing from "../_helpers/applySpacing.mjs";
 import mergeLayoutResults from "../_helpers/mergeLayoutResults.mjs";
-import "./styles.css";
 import maybeDefault from "@niche-works/utils/object/maybeDefault";
 import clsx from "clsx";
 

package/flow/flow.scss.cjs

@@ -0,0 +1 @@
+require('./flow.cjs');

package/flow/flow.scss.d.cts

@@ -0,0 +1 @@
+export { };

package/flow/flow.scss.d.mts

@@ -0,0 +1 @@
+export { };

package/flow/flow.scss.mjs

@@ -0,0 +1,3 @@
+/* empty css      */
+
+export {  };

package/matrix/matrix.cjs

@@ -5,7 +5,6 @@ const require__helpers_hasValue = require('../_helpers/hasValue.cjs');
 const require__helpers_unit = require('../_helpers/unit.cjs');
 const require__helpers_applySpacing = require('../_helpers/applySpacing.cjs');
 const require__helpers_mergeLayoutResults = require('../_helpers/mergeLayoutResults.cjs');
-require('./styles.cjs');
 let _niche_works_utils_object_maybeDefault = require("@niche-works/utils/object/maybeDefault");
 _niche_works_utils_object_maybeDefault = require_runtime.__toESM(_niche_works_utils_object_maybeDefault, 1);
 let clsx = require("clsx");

package/matrix/matrix.mjs

@@ -4,7 +4,6 @@ import hasValue from "../_helpers/hasValue.mjs";
 import unit from "../_helpers/unit.mjs";
 import applySpacing from "../_helpers/applySpacing.mjs";
 import mergeLayoutResults from "../_helpers/mergeLayoutResults.mjs";
-import "./styles.css";
 import maybeDefault from "@niche-works/utils/object/maybeDefault";
 import clsx from "clsx";
 

package/matrix/matrix.scss.cjs

@@ -0,0 +1 @@
+require('./matrix.cjs');

package/matrix/matrix.scss.d.cts

@@ -0,0 +1 @@
+export { };

package/matrix/matrix.scss.d.mts

@@ -0,0 +1 @@
+export { };

package/matrix/matrix.scss.mjs

@@ -0,0 +1,3 @@
+/* empty css        */
+
+export {  };

package/pack/pack.cjs

@@ -2,7 +2,6 @@ const require_runtime = require('../_virtual/_rolldown/runtime.cjs');
 const require_constants = require('../constants.cjs');
 const require__constants = require('../_constants.cjs');
 const require__helpers_applySpacing = require('../_helpers/applySpacing.cjs');
-require('./styles.cjs');
 let _niche_works_utils_object_maybeDefault = require("@niche-works/utils/object/maybeDefault");
 _niche_works_utils_object_maybeDefault = require_runtime.__toESM(_niche_works_utils_object_maybeDefault, 1);
 let clsx = require("clsx");

package/pack/pack.mjs

@@ -1,7 +1,6 @@
 import { clsLayoutPack } from "../constants.mjs";
 import { clsLayoutDirection } from "../_constants.mjs";
 import applySpacing from "../_helpers/applySpacing.mjs";
-import "./styles.css";
 import maybeDefault from "@niche-works/utils/object/maybeDefault";
 import clsx from "clsx";
 

package/pack/pack.scss.cjs

@@ -0,0 +1 @@
+require('./pack.cjs');

package/pack/pack.scss.d.cts

@@ -0,0 +1 @@
+export { };

package/pack/pack.scss.d.mts

@@ -0,0 +1 @@
+export { };

package/pack/pack.scss.mjs

@@ -0,0 +1,3 @@
+/* empty css      */
+
+export {  };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@niche-works/css-layouts",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "keywords": [
     "css",
     "style",
@@ -32,7 +32,15 @@
     "./*/constants": {
       "import": "./*/constants.mjs",
       "require": "./*/constants.cjs"
-    }
+    },
+    "./styles.css": "./styles.css",
+    "./stack.css": "./stack/stack.css",
+    "./flow.css": "./flow/flow.css",
+    "./matrix.css": "./matrix/matrix.css",
+    "./tile.css": "./tile/tile.css",
+    "./balance.css": "./balance/balance.css",
+    "./pack.css": "./pack/pack.css",
+    "./pin.css": "./pin/pin.css"
   },
   "main": "./index.cjs",
   "module": "./index.mjs",

package/pin/pin.cjs

@@ -1,6 +1,5 @@
 const require_constants = require('../constants.cjs');
 const require__helpers_applyChildSize = require('../_helpers/applyChildSize.cjs');
-require('./styles.cjs');
 
 //#region src/pin/pin.ts
 /**

package/pin/pin.mjs

@@ -1,6 +1,5 @@
 import { clsLayoutPin } from "../constants.mjs";
 import applyChildSize from "../_helpers/applyChildSize.mjs";
-import "./styles.css";
 
 //#region src/pin/pin.ts
 /**

package/pin/pin.scss.cjs

@@ -0,0 +1 @@
+require('./pin.cjs');

package/pin/pin.scss.d.cts

@@ -0,0 +1 @@
+export { };

package/pin/pin.scss.d.mts

@@ -0,0 +1 @@
+export { };

package/pin/pin.scss.mjs

@@ -0,0 +1,3 @@
+/* empty css     */
+
+export {  };