postcss-enumerates-in-line 0.3.2 → 1.0.0

package/README.md

@@ -5,24 +5,29 @@
 |[<img width="24" height="24" align="left" src="README.img/1f1ef-1f1f5.png" alt="🇯🇵"> 日本語](README.md)|[<img width="24" height="24" align="left" src="README.img/1f1fa-1f1f8.png" alt="🇺🇸"> English](README_EN.md)|
 
 
-## 更新点: v0.3.2
+## 更新点: v1.0.0
 
-- 以下の条件付きCSSプロパティを追加
-  + `hover!`
-  + `dark!`
-  + `mq(<mediaQueries>)!`
-  + `data(<customDataElements>)`
-  + `aria(<ariaAttributes>)`
-- デフォルトカラーを[Flexoki]に変更
-- `_color.scss`を同梱
-- 作成例の`test/gulp/`と`test/postcss/`を更新
+0. パッケージ全般
 
+- サンプルプログラムの更新
+- メジャーアップデート
 
-## 実装予定
+1. 色設定
+
+- CSSプロパティ値に色設定を行う`color[[...]]`関数を追加
+- プラグインのオプションに色テーマを追加する`appendUserColors(...)`を追加
+- プラグインオプション`prependDefaultColor`の初期設定を`false`に変更
+
+2. ショートハンド設定
 
-- 新しい条件付きCSSプロパティ: `attr(<attributes>)!`
-- ユーザー定義ショートハンド機能
-- `[[...]]`構文の改良と、デフォルトカラーにアルファチャンネルを設定できる`color-alpha[[...]]`構文の追加
+- プラグインのオプションにユーザー定義ショートハンドを拡張する`appendShorthand(...)`を追加
+
+3. CSSプロパティ
+
+- 条件付きCSSプロパティ`attr(<attributes>)!`を追加
+
+
+## 実装予定
 
 
 ---
@@ -52,16 +57,11 @@
 >
 > `my`は`margin-top` & `margin-bottom`の、`ff`は`font-family`の、`fs`は`font-size`のショートハンドです。
 > 何がショートハンドとして定義されているかは[プロパティ名のショートハンド](#プロパティ名のショートハンド)を参照してください。
+> またユーザーが独自にショートハンドを登録することも可能です。
 >
 > `:`記号の前がプロパティ名、後ろがプロパティ値になっています。
 > ホワイトスペースはプロパティの区切り文字であるため、プロパティ値に半角スペース記号を使いたい場合は`^`で代用します。
 
-~~プロパティの列挙を目的としているため、hoverのような状態遷移・メディアクエリ・ダークモードなどへの対応はしません。~~
-
-~~> [Tailwind CSS]における`hover:`・`md:`・`dark:`などに対応する機能は備えていないという意味です。~~
-
-☑️version 0.3.0以上
-
 またCSSプロパティ名の先頭に以下の書式を加筆することで、条件付きCSSプロパティに対応することができます。
 
 - `hover!`: :hover
@@ -69,6 +69,7 @@
 - `mq(<mediaQueries>)!`: @media screen and &lt;mediaQueries&gt;
 - `data(<customDataElements>)!`: [data-&lt;customDataElement&gt;]
 - `aria(<ariaAttributes>)!`: [aria-&lt;ariaAttributes&gt;]
+- `attr(<attributes>)!`: [&lt;attributes&gt;]
 
 > 詳しい書式は目次の次へお進みください。
 
@@ -87,7 +88,7 @@
 ## 目次
 
 - [PostCSS Enumerates in Line](#postcss-enumerates-in-line)
-  - [更新点: v0.3.2](#更新点-v032)
+  - [更新点: v1.0.0](#更新点-v100)
   - [実装予定](#実装予定)
   - [目次](#目次)
   - [CSSでの記述方法](#cssでの記述方法)
@@ -97,6 +98,7 @@
       - [メディアクエリ](#メディアクエリ)
       - [カスタムデータ属性](#カスタムデータ属性)
       - [ARIA属性](#aria属性)
+      - [属性プロパティ](#属性プロパティ)
     - [特殊な記号](#特殊な記号)
       - [コロン記号](#コロン記号)
       - [エクスクラメーション記号](#エクスクラメーション記号)
@@ -104,6 +106,7 @@
       - [二重角括弧記号](#二重角括弧記号)
     - [デフォルトカラー](#デフォルトカラー)
     - [プロパティ名のショートハンド](#プロパティ名のショートハンド)
+      - [ショートハンドのユーザー定義](#ショートハンドのユーザー定義)
   - [プラグインを使用する方法](#プラグインを使用する方法)
     - [gulpでの使い方](#gulpでの使い方)
       - [package.json](#packagejson)
@@ -122,6 +125,10 @@
   - [オプション引数](#オプション引数)
     - [prependDefaultColor](#prependdefaultcolor)
     - [prependDefaultStyle](#prependdefaultstyle)
+    - [appendShorthand](#appendshorthand)
+    - [appendUserColor](#appendusercolor)
+      - [color\[\[...\]\]関数](#color関数)
+      - [prependDefaultColorオプション](#prependdefaultcolorオプション)
 
 <div class="x--hr"></div>
 
@@ -164,7 +171,7 @@ h1 {
 
 上記のように`条件付き書式!CSSプロパティ名:CSSプロパティ値`と記法を拡張することができます。
 
-`hover!`, `dark!`, `mq(...)!`, `data(...)!`, `aria(...)!`はそれぞれ重ね掛けが可能です。
+`hover!`, `dark!`, `mq(...)!`, `data(...)!`, `aria(...)!`, `attr(...)!`はそれぞれ重ね掛けが可能です。
 
 ```scss
 h1 {
@@ -172,7 +179,7 @@ h1 {
 }
 ```
 
-ただしこれら条件付き書式は１つのCSSプロパティにつき１種しか設定できないため、`mq(...)!`・`data(...)!`・`aria(...)!`を連続して記述できません。
+ただしこれら条件付き書式は１つのCSSプロパティにつき１種しか設定できないため、`mq(...)!`・`data(...)!`・`aria(...)!`・`attr(...)!`を連続して記述できません。
 
 列挙する場合は`(`・`)`の中で、`,`を使ってください。
 
@@ -448,6 +455,36 @@ h1[aria-label="heading"] {
 > + `\`: %5D
 
 
+#### 属性プロパティ
+
+カスタムデータ属性（`[data-*]`）とARIA属性（`[aria-*]`）について専用の条件付き書式を設けていますが、それ以外の属性プロパティ（`[*]`）も`attr(...)!`を使うことで記述可能です。
+
+そのため`data(foo="bar")!`と`attr(data-foo="bar")!`は等価になります。
+
+複数の属性セレクターを組み合わせる場合は、`,`で区切ります。
+
+```scss
+/* 🚧Before */
+h1 {
+  @emums attr(download)!ct:red attr(title="heading",data-tags~="hello")!bw2:1px;
+}
+
+/* 🚀After */
+h1[download] {
+  color: red;
+}
+h1[title="heading"][data-tags~="hello"] {
+  border-bottom-width: 1px;
+}
+```
+
+属性セレクターは`属性名`、または`属性名`・`条件演算子`・`属性データ`の組み合わせになっています。
+
+属性名が存在することだけを条件にする場合は、`条件演算子`と`属性データ`を必要としません。
+
+詳細は[カスタムデータ属性](#カスタムデータ属性)を参照してください。
+
+
 ### 特殊な記号
 
 特殊な振る舞いを起こす文字は、`:`・`^`・`!`・`[[`・`]]`の５種類です。
@@ -512,47 +549,59 @@ h1[aria-label="heading"] {
 
 しかし変換書式を改善中であるため、意図したように演算子の両端へ正常に空白記号が挿入されない可能性があります。
 
-こうした場合でも`^`記号を補えば正常な算術関数へと修正できるのですが、より確実な手段としては`[[`・`]]`記号を使わず人力で`^`記号を補う方が間違いは少ないでしょう。
+> こうした場合でも`^`記号を補えば正常な算術関数へと修正できるのですが、より確実な手段としては`[[`・`]]`記号を使わず人力で`^`記号を補う方が間違いは少ないでしょう。
 
+---
 
+上記とは別に、`color[[...]]`という独自の構文をCSSプロパティ値に使用することができます。
 
-### デフォルトカラー
+```scss
+h1 {
+  @enums ct:color[[yellow,600]];
+}
+```
 
-デフォルトカラーは[Flexoki] v2.0からのフォークです。
+`,`区切りの複数の引数を取ることができ、この[パッケージが管理する色情報](README.img/default_color.png)を呼び出すために使います。
 
-CSSの`var()`関数を使い、CSS変数から呼び出して使用します。
+これはプラグインオプションの`prependDefaultColor`を`true`にした上で、`@enums ct:var(--color-yellow-600);`を宣言した時と同じ挙動をします。
 
 ```scss
-body {
-  @enums ct:var(--color-red-400);
+h1 {
+  @enums ct:color[[cyan,400,95%,rgb]];
 }
 ```
 
-[<img src="README.img/default_color.png" alt="Default color">](README.img/default_color.png)
+この関数様の構文は、最大で４種類の引数を取ります。
 
-しかし現状では`#RRGGBBAA`書式のアルファチャンネル付き色設定ができないため、`_color.scss`を同梱しています。
+1. 色テーマ（`cyan`など）
+2. 濃度レベル（`400`など; 正規表現で書くと`/[\d]+/`）
+3. アルファ値（`95%`など; 正規表現で書くと`/[\d]+[%]/`）
+4. 出力形式（`rgb`|`hsl`|`oklch`; 大文字小文字は問いません）
 
-```scss
-@use '../node_modules/postcss-enumerates-in-line/_color.scss' as c;
+既に登録されている色テーマ名を指定することはできません。
 
-html {
-  color: #{c.$color-red-400}99; // D14D4199
-}
-```
+これはプラグインが初期状態で実装しているものだけでなく、ユーザー定義による追加された色テーマについても同様です。
 
-> 将来的には`color-alpha[[<color-theme>,<color-depth>,<alpha>,<optional:output-style>]]`関数の実装を予定しています。
+> 未指定の種類に対しては、次の初期値が適用されます。
+> 1. `base`
+> 2. `400`
+> 3. `100%`
+> 4. `hsl`
+>
+> 未定義の色テーマや濃度レベルを指定した場合、エラーとして扱われ無視されます。
 
-```scss
-/* 🚧Before */
-html {
-  color: color-alpha[[red,400,60%,oklch]];
-}
+この関数を使うことで、透過率が設定できる他、色テーマをプラグインのオプションである`appendUserColors(...)`でユーザー独自の定義を追加できる上に、`prependDefaultColor`を初期値の`false`以外にするとCSS変数として色情報が`:root`ブロックに出力されることでCSSファイルサイズが大きくなるなど、様々なデメリットが解消されるでしょう。
 
-/* 🚀After */
-html {
-  color: oklch(0.597 0.1692 28.38 / 60%);
-}
-```
+
+### デフォルトカラー
+
+デフォルトカラーは[Flexoki] v2.0からのフォークです。
+
+[<img src="README.img/default_color.png" alt="Default color">](README.img/default_color.png)
+
+`color[[...]]`の項目で説明した通り、`appendUserColors(...)`オプション設定を使うと独自の色テーマを追加することができます。
+
+詳細は[オプション引数](#オプション引数)を参照してください。
 
 
 ### プロパティ名のショートハンド
@@ -649,6 +698,13 @@ html {
 数字の`1`から`9`が使われる理由はテンキーの配置を想像してみてください。
 
 
+#### ショートハンドのユーザー定義
+
+CSSプロパティ名のショートハンドは、プラグインオプションの`appendShorthand(...)`により拡張することができます。
+
+詳細は[オプション引数](#オプション引数)を参照してください。
+
+
 ## プラグインを使用する方法
 
 ### gulpでの使い方
@@ -727,6 +783,8 @@ PostCSS処理の配列の中に、`enumSpreader({})`関数を差し込みます
 
 この関数は初期設定のまま利用する場合は空のオブジェクトを指定します。
 
+> サンプルプログラムではユーザー定義のショートハンドを追加する設定を行っています。
+
 動作を変更したい場合は引数にオプション設定を加えます。
 
 設定内容は[オプション引数](#オプション引数)を参照してください。
@@ -841,6 +899,8 @@ PostCSS処理の配列の中に、`enumSpreader({})`関数を差し込みます
 
 この関数は初期設定のまま利用する場合は空のオブジェクトを指定します。
 
+> サンプルプログラムではユーザー定義のショートハンドを追加する設定を行っています。
+
 動作を変更したい場合は引数にオプション設定を加えます。
 
 設定内容は[オプション引数](#オプション引数)を参照してください。
@@ -864,9 +924,9 @@ PostCSS処理の配列の中に、`enumSpreader({})`関数を差し込みます
 
 自動的に出力される色設定への対応内容。
 
-初期値: true (boolean|string)
+初期値: false (boolean|string)
 
-`true`を設定した時（または何も設定しなかった時、あるいは`"hsl"`や`"HSL"`を設定した時）において、次のような色設定（HSL形式）がCSSに出力されます。
+`true`を設定した時（または`"hsl"`や`"HSL"`を設定した時）において、次のような色設定（HSL形式）がCSSに出力されます。
 
 ```css
 :root {
@@ -924,3 +984,179 @@ prependDefaultStyle: [
 追記するだけであって、このプラグインが最初から搭載しているリセットCSSの一部だけを除去することはできません。
 
 完全に自己流のリセットCSSだけを出力したい場合は`prependDefaultStyle`オプションを`false`にした上で、SCSSファイルにその設定を記述してください。
+
+
+### appendShorthand
+
+ユーザー定義ショートハンドの追加。
+
+初期値: [] (string[string,string[]])
+
+```javascript
+appendShorthand: [
+  ['pos', ['position']],
+],
+```
+
+上記のように指定すると、`pos`が新たに`position`のショートハンドとして機能するようになります。
+
+```javascript
+appendShorthand: [
+  ['bw246', ['border-bottom-width', 'border-left-width', 'border-right-width']],
+],
+```
+
+複数のプロパティ名を一括指定することも可能です。
+
+```javascript
+appendShorthand: [
+  ['lh', ['line-height']],
+],
+```
+
+`line-height`プロパティには既に`fh`というショートハンドが存在していますが、別名（エイリアス）のショートハンドを与えることもできます。
+
+```javascript
+appendShorthand: [
+  ['o', ['opacity']],
+],
+```
+
+しかし上記のように`o`を登録しようとしても、`outline`のショートハンドとして既に登録されているため無視されます。
+
+ショートハンドの設定上書きはできません。
+
+また構文エラーの場合は無視されます。
+
+
+### appendUserColor
+
+ユーザー定義色テーマの追加。
+
+初期値: [] ({theme: &lt;string&gt;, levels: {level: &lt;number&gt;, rgb: &lt;string&gt;, hsl: &lt;string&gt;, oklch: &lt;string&gt;}[]}[])
+
+```javascript
+appendUserColor: [
+  {
+    theme: 'blood',
+    levels: [
+      {
+        level: 400,
+        rgb: '#660000',
+        hsl: 'hsl(0 100% 20%)',
+        oklch: 'oklch(0.3204 0.1315 29.23)',
+      },
+      {
+        level: 600,
+        rgb: '#D1001C',
+        hsl: 'hsl(352 100% 41%)',
+        oklch: 'oklch(0.5418 0.2202 26.04)',
+      },
+    ]
+  },
+]
+```
+
+上記のように指定すると、`theme`の`blood`が新しい色テーマとして登録され、濃度レベルは`400`と`600`が利用可能になります。
+
+> デフォルトカラーとして登録されている色テーマ名や、別のユーザー定義色テーマ名とは重複する名称を登録することはできません。
+
+登録済みの色テーマは、次の２種類の方法で呼び出すことが可能です。
+
+1. `color[[...]]`
+2. `prependDefaultColor`
+
+
+#### color[[...]]関数
+
+```scss
+/* 🚧Before */
+h1 {
+  @enums ct:color[[red,400]];
+}
+
+/* 🚀After */
+h1 {
+  color: hsl(5 61% 53.7%);
+}
+```
+
+色テーマ名（例: `red`）・濃度レベル（例: `400`）・アルファ値（例: `100%`）・出力形式（例: `rgb`）の最大４種類を引数に取り、全てオプション引数であるため省略が可能です。
+
+ただし構文上の制約から、最低１種類は引数として指定してください。
+
+> 1. 色テーマ名
+>
+> デフォルトカラーまたは`appendUserColor(...)`で登録したもの。
+>
+> 省略された場合の初期値は`base`。
+>
+> 未定義の色テーマ名を指定した場合、内部エラー処理により無視されます。
+
+> 2. 濃度レベル
+>
+> `0`（輝度ほぼ100％）から`999`（輝度ほぼ0％）までの整数
+>
+> 省略された場合の初期値は`400`
+>
+> デフォルトカラーはだいたい100区切りの分かりやすい数値になっていますが、`appendUserColor(...)`で登録する場合は独自の数値を与えることが可能です。
+>
+> 未定義の濃度レベルを指定した場合、内部エラー処理により無視されます。
+
+> 3. アルファ値
+>
+> `0%`（完全に透明）から`100%`（完全に不透明）までのパーセント値
+>
+> 省略された場合の初期値は`100%`
+>
+> `50.5%`のような小数点指定も可能ですが、`1`のようにしてパーセント記号を省略すると濃度レベルだと誤解釈してしまうため必ずパーセント記号を付けてください。
+
+> 4. 出力形式
+>
+> CSSファイルへ出力する時の書式
+>
+> 省略された場合の初期値は`hsl`
+>
+> `hsl`・`rgb`・`oklch`の３種類から選択できます。大文字小文字は問いません。
+
+
+#### prependDefaultColorオプション
+
+```javascript
+enumSpreader({
+  prependDefaultColor: true,
+  // ...
+})
+```
+
+プラグインオプションの`prependDefaultColor`を`false`以外の値にすると、色テーマに関するCSS変数が出力されます。
+
+> 指定可能な値は`hsl`・`rgb`・`oklch`、および`true`（`hsl`と等価）です。
+>
+> `true`以外の文字列リテラルに限り、大文字小文字は問いません。
+
+```css
+:root {
+  --color-red-400: hsl(5 61% 53.7%);
+}
+```
+
+この設定を利用して、色設定を行います。
+
+```scss
+/* 🚧Before */
+h1 {
+  @enums ct:var(--color-red-400);
+}
+
+/* 🚀After */
+h1 {
+  color: hsl(5 61% 53.7%);
+}
+```
+
+この方法のメリットは、PostCSS Enumerates in Lineプラグインの外ででも色設定を利用することができる点にあります。
+
+しかしアルファ値の設定ができなかったり、あるいは大量に出力されるCSS変数のためCSSファイルのサイズが肥大化したりする点はデメリットです。
+
+状況に応じて使い分けてください。