postcss-enumerates-in-line 0.1.1 → 0.3.0

package/README.md

@@ -5,9 +5,24 @@
 |[<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.1.0
+## 更新点: v0.3.0
+
+- 以下の条件付きCSSプロパティを追加
+  + `hover!`
+  + `dark!`
+  + `mq(<mediaQueries>)!`
+  + `data(<customDataElements>)`
+  + `aria(<ariaAttributes>)`
+- デフォルトカラーを[Flexoki]に変更
+- `_color.scss`を同梱
+- 作成例の`test/gulp/`と`test/postcss/`を更新
+
+
+## 実装予定
+
+- ユーザー定義ショートハンド機能
+- `[[...]]`構文の改良と、デフォルトカラーにアルファチャンネルを設定できる`color-alpha[[...]]`構文の追加
 
-- サンプルのパッケージ読み込みを[npmjs.com](https://www.npmjs.com/)経由に変更
 
 ---
 
@@ -39,12 +54,22 @@
 >
 > `:`記号の前がプロパティ名、後ろがプロパティ値になっています。
 > ホワイトスペースはプロパティの区切り文字であるため、プロパティ値に半角スペース記号を使いたい場合は`^`で代用します。
->
-> 詳しい書式は目次の次へお進みください。
 
-プロパティの列挙を目的としているため、hoverのような状態遷移・メディアクエリ・ダークモードなどへの対応はしません。
+~~プロパティの列挙を目的としているため、hoverのような状態遷移・メディアクエリ・ダークモードなどへの対応はしません。~~
 
-> [Tailwind CSS]における`hover:`・`md:`・`dark:`などに対応する機能は備えていないという意味です。
+~~> [Tailwind CSS]における`hover:`・`md:`・`dark:`などに対応する機能は備えていないという意味です。~~
+
+☑️version 0.3.0以上
+
+またCSSプロパティ名の先頭に以下の書式を加筆することで、条件付きCSSプロパティに対応することができます。
+
+- `hover!`: :hover
+- `dark!`: :root.dark
+- `mq(<mediaQueries>)!`: @media screen and &lt;mediaQueries&gt;
+- `data(<customDataElements>)!`: [data-&lt;customDataElement&gt;]
+- `aria(<ariaAttributes>)!`: [aria-&lt;ariaAttributes&gt;]
+
+> 詳しい書式は目次の次へお進みください。
 
 基本的には[gulp]および[gulp-postcss]での動作を想定していますが、JS-APIによるPostCSS単体でも動作します。
 
@@ -53,6 +78,7 @@
 [SCSS]: https://sass-lang.com/
 [gulp]: https://gulpjs.com/
 [gulp-postcss]: https://github.com/postcss/gulp-postcss
+[Flexoki]: https://stephango.com/flexoki
 
 <div class="x--hr"></div>
 
@@ -60,14 +86,22 @@
 ## 目次
 
 - [PostCSS Enumerates in Line](#postcss-enumerates-in-line)
-  - [更新点: v0.1.0](#更新点-v010)
+  - [更新点: v0.3.0](#更新点-v030)
+  - [実装予定](#実装予定)
   - [目次](#目次)
   - [CSSでの記述方法](#cssでの記述方法)
+    - [条件付き書式](#条件付き書式)
+      - [ダークモード](#ダークモード)
+      - [マウスオーバー](#マウスオーバー)
+      - [メディアクエリ](#メディアクエリ)
+      - [カスタムデータ属性](#カスタムデータ属性)
+      - [ARIA属性](#aria属性)
     - [特殊な記号](#特殊な記号)
       - [コロン記号](#コロン記号)
       - [エクスクラメーション記号](#エクスクラメーション記号)
       - [サーカムフレックス記号](#サーカムフレックス記号)
       - [二重角括弧記号](#二重角括弧記号)
+    - [デフォルトカラー](#デフォルトカラー)
     - [プロパティ名のショートハンド](#プロパティ名のショートハンド)
   - [プラグインを使用する方法](#プラグインを使用する方法)
     - [gulpでの使い方](#gulpでの使い方)
@@ -100,7 +134,7 @@ html {
   @enums background-color:#000 color:#fff;
 
   h1 {
-    @enums font-size:100%;
+    @enums font-size:100% hover!color:red;
   }
 }
 ```
@@ -116,6 +150,303 @@ CSSスタイル宣言についても単純で、「`プロパティ名`・`半
 プロパティ値は任意の値を取ることができるため、`border:1px^#888^solid`など自由な指示をすることができるでしょう。
 
 
+### 条件付き書式
+
+```scss
+h1 {
+  @emums data(visible="hidden")!display:none
+  ct:blue hover!ct:red
+  cb:white dark!cb:black
+  mq(width:1000px-)!mx:auto;
+}
+```
+
+上記のように`条件付き書式!CSSプロパティ名:CSSプロパティ値`と記法を拡張することができます。
+
+`hover!`, `dark!`, `mq(...)!`, `data(...)!`, `aria(...)!`はそれぞれ重ね掛けが可能です。
+
+```scss
+h1 {
+  @enums dark!hover!ct:red;
+}
+```
+
+ただしこれら条件付き書式は１つのCSSプロパティにつき１種しか設定できないため、`mq(...)!`・`data(...)!`・`aria(...)!`を連続して記述できません。
+
+列挙する場合は`(`・`)`の中で、`,`を使ってください。
+
+同種の条件付き書式を重複させた場合、最初のものだけが適用され、残りの指定内容は無視されます。
+
+```scss
+/* ❌️NG */
+h1 {
+  @enums mq(width:-640px)!mq(orientation:portrait)!m2:auto
+  data(state="succeed")!data(target-href^="https://")!text-indent:1rem;
+}
+
+/* ⭕️OK */
+h1 {
+  @enums mq(width:-640px,orientation:portrait)!m2:auto
+  data(state="succeed",target-href^="https://")!text-indent:1rem;
+}
+
+/* 🙂Unzip */
+@media screen and (max-width: 640px) and (orientation: portrait) {
+  h1 {
+    margin-bottom: auto;
+  }
+}
+h1[data-state="succeed"][data-target-href^="https://"] {
+  text-indent: 1rem;
+}
+```
+
+
+#### ダークモード
+
+条件付き書式`dark!`を使うと、`root:`（html要素）に`dark`クラスが存在するかどうかで判定できるようになります。
+
+```scss
+/* 🚧Before */
+h1 {
+  @emums cb:white dark!cb:black;
+}
+
+/* 🚀After */
+h1 {
+  background-color: white;
+}
+:root.dark h1 {
+  background-color: black;
+}
+```
+
+
+#### マウスオーバー
+
+条件付き書式`hover!`を使うと、`:hover`（マウスオーバー状態）擬似クラスを追加できます。
+
+```scss
+/* 🚧Before */
+h1 {
+  @emums ct:blue hover!ct:red;
+}
+
+/* 🚀After */
+h1 {
+  color: blue;
+}
+h1:hover {
+  color: red;
+}
+```
+
+
+#### メディアクエリ
+
+条件付き書式`mq(<mediaQueries>)!`を使うと、`@media`ルールの中に入れることができます。
+
+複数のメディアクエリを組み合わせる場合は、`,`で区切ります。
+
+```scss
+/* 🚧Before */
+h1 {
+  @emums mq(width:1000px-)!m2:auto
+  mq(height:-1000px,aspect-ratio:1-)!p:1.5rem;
+}
+
+/* 🚀After */
+@media screen and (min-width: 1000px) {
+  h1 {
+    margin-bottom: auto;
+  }
+}
+@media screen and (max-height: 1000px) and (min-aspect-ratio: 1) {
+  h1 {
+    padding: 1.5rem;
+  }
+}
+```
+
+`mq(...)`関数の引数となるメディアクエリは、`メディア特性`・`:`・`条件値`の組み合わせになっています。
+
+利用可能なメディア特性は次の通りですが、条件値によって出力される実際のメディア特性が変化します。
+
+- `orientation`: orientation
+- `width`: width, min-width, max-width
+- `height`: height, min-height, max-height
+- `aspect-ratio`: aspect-ratio, min-aspect-ratio, max-aspect-ratio
+
+> `orientation`に指定可能な条件値は、`portrait`（縦長または正方形）と`landscape`（横長）のいずれかのみです。
+
+```scss
+body {
+  @enums
+  mq(orientation:portrait)!m2:1rem
+  mq(orientation:landscape)!m8:1rem
+  ;
+}
+```
+
+> `width`に指定可能な条件値は、`-<length>`・`<length>-<length>`・`<length>-`の３種類です。
+>
+> `<length>`に指定可能なのは`px`・`rem`・`vw`など長さに関わる値です。
+>
+> + １つのみある`<length>`の前に`-`を付けた場合、`<length>`以下のメディアクエリを意味します（適用されるメディア特性は`max-width`）
+> + ２つの`<length>`を`-`で接続した場合、その区間以内であるメディアクエリを意味します（適用されるメディア特性は`min-width`と`max-width`）
+> + １つのみある`<length>`の後ろに`-`を付けた場合、`<length>`以上のメディアクエリを意味します（適用されるメディア特性は`min-width`）
+
+```scss
+body {
+  @enums
+  mq(width:-480px)!m2:1rem
+  mq(width:640px-1024px)!mx:1rem
+  mq(width:1280px)!m8:1rem
+  ;
+}
+```
+
+> `height`に指定可能な条件値、および動作は`width`と同じです。
+>
+> ただし適用されるメディア特性は、`height`・`min-height`・`max-height`に変化します。
+
+```scss
+body {
+  @enums
+  mq(height:-480px)!m2:1rem
+  mq(height:640px-1024px)!mx:1rem
+  mq(height:1280px)!m8:1rem
+  ;
+}
+```
+
+> `aspect-ratio`に指定可能な条件値は、`整数値`（1など）または`小数値`（0.85など）です。
+>
+> `@media (aspect-ratio: 16/9)`のような除算記号（`/`）を使った表記はできません。
+>
+> `width`・`height`に似た表記が可能で、`-<number>`・`<number>-<number>`・`<number>-`の３種類と`<number>`が実際に指定可能な条件値です。
+>
+> + １つのみある`<number>`の前に`-`を付けた場合、`<number>`以下のメディアクエリを意味します（適用されるメディア特性は`max-aspect-ratio`）
+> + ２つの`<number>`を`-`で接続した場合、その区間以内であるメディアクエリを意味します（適用されるメディア特性は`min-aspect-ratio`と`max-aspect-ratio`）
+> + １つのみある`<number>`の後ろに`-`を付けた場合、`<number>`以上のメディアクエリを意味します（適用されるメディア特性は`min-aspect-ratio`）
+> + `<number>`が１つのみあって`-`がない場合、アスペクト比が`<number>`とまったく等しい状態を意味します（適用されるメディア特性は`aspect-ratio`）
+
+```scss
+body {
+  @enums
+  mq(aspect-ratio:-0.5)!m2:1rem
+  mq(aspect-ratio:0.55-0.95)!mx:1rem
+  mq(aspect-ratio:1.25-)!m8:1rem
+  mq(aspect-ratio:1)!p:1rem
+  ;
+}
+```
+
+
+#### カスタムデータ属性
+
+条件付き書式`data(<customDataElements>)!`を使うと、`[data-foo="bar"]`のようなカスタムデータによる属性セレクターを追加できます。
+
+複数の属性セレクターを組み合わせる場合は、`,`で区切ります。
+
+```scss
+/* 🚧Before */
+h1 {
+  @emums data(visible="hidden")!display:none;
+}
+
+/* 🚀After */
+h1[data-visible="hidden"] {
+  display: none;
+}
+```
+
+属性セレクターは`属性名`、または`属性名`・`条件演算子`・`属性データ`の組み合わせになっています。
+
+属性名が存在することだけを条件にする場合は、`条件演算子`と`属性データ`を必要としません。
+
+```scss
+/* 🚧Before */
+h1 {
+  @enums data(loading)!display:none
+  data(is-empty="false")!m8:1rem;
+}
+
+/* 🚀After */
+h1[data-loading] {
+  display: none;
+}
+h1[data-is-empty="false"] {
+  margin-top: 1rem;
+}
+```
+
+> 属性名には`data-`に続く文字列を指定します。
+>
+> 具体的には`/[A-Za-z\d_\-]/`の文字が使用可能ですが、属性名の始端または終端を`-`の文字列とすることはできません。
+
+> 条件演算子には次の種類を使用することができます。
+> + `=`: 属性データと一致する場合（`[data-foo="bar"]`）
+> + `~=`: 属性データが空白記号区切りリストであり、その中の１つと一致する場合（`[data-tags~="ipsum"]`, `<span data-tags="lorem ipsum dolor sit amet"></span>`）
+> + `^=`: 属性データの文字列で始まる場合（`[data-href^="https://"]`）
+> + `$=`: 属性データの文字列で終わる場合（`[data-href$=".webp"]`）
+> + `*=`: 属性データの文字列を含む場合（`[data-alphabet*="bcdef"]`）
+> + `|=`: 属性データと一致する文字列で始まり、かつその後ろに半角ハイフン記号を伴う場合（`[data-lang|="en"]`）
+>
+> > 言語タグとして`en-US`や`en-GB`など、ISO 639 + ISO 3166による表現を行う場合に利用されることの多い表現です。
+
+> 属性データは、`"`または`'`で囲まれている必要があります。
+>
+> このため引用符を使う場合は注意してください。
+>
+> またパッケージの内部処理により、以下の文字が属性データに含まれる場合はパーセントエンコーディングを行います。
+> + `%`: %25
+> + `"`: %22
+> + `'`: %27
+> + `｀`: %60
+> + `\`: %5D
+
+
+#### ARIA属性
+
+条件付き書式`aria(<ariaAttributes>)!`を使うと、`[aria-label="heading"]`のようなARIA属性によるセレクターを追加できます。
+
+複数の属性セレクターを組み合わせる場合は、`,`で区切ります。
+
+```scss
+/* 🚧Before */
+h1 {
+  @emums aria(label="heading")!fs:1.5rem;
+}
+
+/* 🚀After */
+h1[aria-label="heading"] {
+  font-size: 1.5rem;
+}
+```
+
+属性セレクターは`属性名`・`=`・`属性データ`の組み合わせになっています。
+
+> 属性名には`aria-`に続く文字列を指定します。
+>
+> `/[a-z]/`の文字しか使うことはできません。
+
+> 条件演算子は現在`=`のみを有効にしています。
+>
+> 必要になれば`data(...)!`と同等の条件にまで拡張するかもしれません。
+
+> 属性データは、`"`または`'`で囲まれている必要があります。
+>
+> このため引用符を使う場合は注意してください。
+>
+> またパッケージの内部処理により、以下の文字が属性データに含まれる場合はパーセントエンコーディングを行います。
+> + `%`: %25
+> + `"`: %22
+> + `'`: %27
+> + `｀`: %60
+> + `\`: %5D
+
+
 ### 特殊な記号
 
 特殊な振る舞いを起こす文字は、`:`・`^`・`!`・`[[`・`]]`の５種類です。
@@ -134,6 +465,8 @@ CSSスタイル宣言についても単純で、「`プロパティ名`・`半
 
 `padding-top:1rem!`などのようにして、`!`記号をプロパティ値の末尾に付けると`!important`宣言をしたことになります。
 
+> 条件付き書式の`!`とは働きが異なるためご注意ください。
+
 
 #### サーカムフレックス記号
 
@@ -173,7 +506,7 @@ CSSスタイル宣言についても単純で、「`プロパティ名`・`半
 `width:calc(100vw^-^(100%^+^2rem)^*^2^+^1rem)`のような記述は視覚的ではないため、`[[`と`]]`に囲んだ中であれば`width:calc[[100vw-(100%+2rem)*(2)+1rem]]`としてサーカムフレックス記号を省くことができます。
 
 > `var`関数など算術関数でないものに`[[`・`]]`記号は使わないでください。
-> 
+>
 > 例えば`var(--foo-bar)`が誤変換されて、`var(--foo - bar)`のようにして意味のないCSSへと破壊されてしまうためです。
 
 しかし変換書式を改善中であるため、意図したように演算子の両端へ正常に空白記号が挿入されない可能性があります。
@@ -181,6 +514,46 @@ CSSスタイル宣言についても単純で、「`プロパティ名`・`半
 こうした場合でも`^`記号を補えば正常な算術関数へと修正できるのですが、より確実な手段としては`[[`・`]]`記号を使わず人力で`^`記号を補う方が間違いは少ないでしょう。
 
 
+
+### デフォルトカラー
+
+デフォルトカラーは[Flexoki] v2.0からのフォークです。
+
+CSSの`var()`関数を使い、CSS変数から呼び出して使用します。
+
+```scss
+body {
+  @enums ct:var(--color-red-400);
+}
+```
+
+[<img src="README.img/default_color.png" alt="Default color">](README.img/default_color.png)
+
+しかし現状では`#RRGGBBAA`書式のアルファチャンネル付き色設定ができないため、`_color.scss`を同梱しています。
+
+```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>]]`関数の実装を予定しています。
+
+```scss
+/* 🚧Before */
+html {
+  color: color-alpha[[red,400,60%,oklch]];
+}
+
+/* 🚀After */
+html {
+  color: oklch(0.597 0.1692 28.38 / 60%);
+}
+```
+
+
 ### プロパティ名のショートハンド
 
 いくつかのプロパティ名にはショートハンド定義がしてあります。
@@ -496,7 +869,7 @@ PostCSS処理の配列の中に、`enumSpreader({})`関数を差し込みます
 
 ```css
 :root {
-  --enums-color-gray-100: hsl(210 5% 10%);
+  --color-red-400: hsl(5 61% 53.7%);
 }
 ```
 
@@ -506,7 +879,7 @@ PostCSS処理の配列の中に、`enumSpreader({})`関数を差し込みます
 
 ```css
 :root {
-  --enums-color-gray-100: #181a1b;
+  --color-red-400: #D14D41;
 }
 ```
 
@@ -514,7 +887,7 @@ PostCSS処理の配列の中に、`enumSpreader({})`関数を差し込みます
 
 ```css
 :root {
-  --enums-color-gray-100: oklch(0.21 0.01 210);
+  --color-red-400: oklch(0.597 0.1692 28.38);
 }
 ```