@charcoal-ui/icons 6.0.0-beta.0 → 6.0.0-beta.2

package/src/SSR.mdx

@@ -8,58 +8,142 @@ import { Meta, Story, Canvas } from '@storybook/addon-docs/blocks'
 `@charcoal-ui/icons` は、Node.js の環境下で import されたり、API を呼び出されても問題が起きないように設計されています。
 
 一方、Custom Element であるということは、**SVG アイコンの読み込みはクライアントサイドで行われます**。  
-したがって、大きさが確定せずにレイアウトシフトが起こりうるのは、SSR における注意点の一つと言えます。
-
-以下のようなコードをリセット CSS に含めることで、`<pixiv-icon>` によるレイアウトシフトの発生を防ぐことができます。  
-（簡単のため、ネスト記法が利用できるケースを意図しています）
-
-```css
-pixiv-icon {
-  display: inline-flex;
-  width: calc(var(--icon-size, 1em) * var(--scale, 1));
-  height: calc(var(--icon-size, 1em) * var(--scale, 1));
-}
-
-&[name~='16/'] {
-  --icon-size: 16px;
-}
-
-&[name~='24/'] {
-  --icon-size: 24px;
-}
-
-&[name~='32/'] {
-  --icon-size: 32px;
-}
-
-&[scale='2'] {
-  --scale: 2;
-}
-
-&[scale='3'] {
-  --scale: 3;
-}
-
-/* NOTICE: 現状とサポートブラウザが少ない */
-@supports (--scale: attr(unsafe-non-guideline-scale)) {
-  &[unsafe-non-guideline-scale] {
-    --scale: attr(unsafe-non-guideline-scale);
-  }
-}
+したがって、大きさが確定せずにレイアウトシフト (CLS) が起こりうるのは、SSR における注意点の一つと言えます。
+
+## なぜ CSS が必要なのか
+
+`@charcoal-ui/icons` の JS が読み込まれて `customElements.define('pixiv-icon', ...)` が実行されるまで、`<pixiv-icon>` は Shadow DOM を持たない単なる未登録 Custom Element です。CSS がない場合、ブラウザはこの要素のサイズを 0x0 として扱うため:
+
+- SSR で送出された HTML が画面に描画された直後: アイコンは **0x0** で何も見えない
+- JS がロードされて `pixiv-icon` が `:defined` になった瞬間: 突然 16x16 / 24x24 などの実サイズになり、**周囲のコンテンツが押し出される**
+
+この瞬間に発生する CLS を、`icon.css` が事前に寸法を確保することで防ぎます。
+
+## レイアウトシフト防止 CSS
+
+`@charcoal-ui/icons/css/icon.css` をインポートすると、`<pixiv-icon>` のレイアウトシフトを防止できます。
+アプリケーションのエントリポイント、または Storybook の `preview.(js|ts)` で 1 度だけ読み込んでください。
+
+```ts
+import '@charcoal-ui/icons/css/icon.css'
 ```
 
-ただしコメントにもある通り、**現状 `unsafe-non-guideline-scale` をつけた要素は、リセット CSS だけではレイアウトシフトが防げません。**
-CSS の `attr()` が数値の解釈をサポートするまで、個別にインラインスタイルを用いて大きさを確定させるなどのワークアラウンドが必要です。
+この CSS は 2 つのメカニズムを提供します。
+
+### 1. `.charcoal-icon` クラス（React 向け）
+
+`@charcoal-ui/react` の `<Icon>` コンポーネントは自動的に `.charcoal-icon` クラスと `--charcoal-icon-size` CSS 変数を設定します。
+CSS が読み込まれていれば、Custom Element の定義前でも正しいサイズが確保されます。
+
+### 2. `pixiv-icon:not(:defined)` セレクター（vanilla HTML 向け）
+
+React を使わない場合でも、`name` 属性のプレフィックス（`16/`, `24/`, `32/`, `Inline/`）と `scale` 属性に基づいてサイズが確保されます。
+
+## サイズ決定ルール
+
+サイズの決定タイミングは hydrate の前後で異なります。
+
+### hydrate 前 (`pixiv-icon:not(:defined)` の段階)
+
+1. **`style="--charcoal-icon-size: Npx"` が指定されていれば、その値を使う**（最優先）
+2. それ以外は `name` プレフィックスと `scale` 属性から導出されたガイドラインデフォルトを使う
+
+`fixed-size` / `unsafe-non-guideline-scale` 属性は CSS の `attr()` での
+数値解釈に制約があるためこの段階では参照できず、暫定値が表示されます。
+**ガイドライン外のサイズで CLS を完全に防ぐには、必ず `style="--charcoal-icon-size: Npx"` をインラインで併記してください** (React の `<Icon fixedSize>` 経由なら自動で付与されます)。
+
+### hydrate 後 (`:defined` 状態)
+
+JS が読み込まれて web component が定義されると、`render()` が以下の優先順で size を計算し、
+**結果を `--charcoal-icon-size` の inline style に上書きします**。
+
+1. `fixed-size` 属性（最優先 / ピクセル値）
+2. `unsafe-non-guideline-scale` 属性 × `name` のベースサイズ（**deprecated**）
+3. `name` プレフィックスと `scale` 属性から導出されたガイドラインデフォルト
+
+つまりユーザーが書いた `style="--charcoal-icon-size: ..."` は **hydrate 後には属性ベースの計算結果で上書きされる** 点に注意してください。永続的に上書きしたい場合は属性で指定します。
 
 ```html
+<!-- ガイドライン通り 24px -->
+<pixiv-icon name="24/Add"></pixiv-icon>
+
+<!-- ガイドライン通り 48px (24 × scale=2) -->
+<pixiv-icon name="24/Add" scale="2"></pixiv-icon>
+
+<!-- 12px に固定 (hydrate 後も 12px のまま)。SSR の CLS を避けるため style も併記 -->
 <pixiv-icon
   name="24/Add"
-  unsafe-non-guideline-scale="0.5"
-  style="--scale: 0.5;"
+  fixed-size="12"
+  style="--charcoal-icon-size: 12px"
+></pixiv-icon>
+```
+
+### `scale` 属性のプレフィックスごとの挙動
+
+`name` プレフィックスごとに `scale` のサポート範囲が異なります。表に整理すると以下の通りです。
+
+| プレフィックス | `scale=1` | `scale=2` | `scale=3` | 備考                              |
+| -------------- | --------- | --------- | --------- | --------------------------------- |
+| `16/`          | 16        | **16**    | **16**    | `scale` を無視（意図的な仕様）    |
+| `24/`          | 24        | 48        | 72        | すべて対応                        |
+| `32/`          | 32        | **32**    | **32**    | `scale` を無視（意図的な仕様）    |
+| `Inline/`      | 16        | 32        | **16**    | `scale=3` は `scale=1` と同じ扱い |
+
+`scale` に対応していない組み合わせを書いても **CLS は発生しません**（CSS と JS 双方で同じ結果を返すように揃えてあります）が、期待通りに大きくならないことに注意してください。
+大きく表示したい場合は次節の「ガイドライン外のサイズ指定」を使ってください。
+
+### ガイドライン外のサイズ指定
+
+ガイドライン外のサイズを使う場合は **`fixed-size` (vanilla HTML) / `fixedSize` (React)** を使います。
+`fixed-size` は他のサイズ指定 (`scale` / `unsafe-non-guideline-scale`) よりも常に優先されます。
+
+#### React (`<Icon fixedSize={N}>`)
+
+```jsx
+<Icon name="24/Add" fixedSize={12} />  {/* 12px 固定 */}
+<Icon name="24/Add" fixedSize={40} />  {/* 40px 固定 */}
+```
+
+`<Icon>` は同じ値を `--charcoal-icon-size` インライン CSS 変数として自動付与するため、
+**hydrate 前後とも正しいサイズで CLS は起きません**。利用者側で追加の対応は不要です。
+
+#### vanilla HTML (`<pixiv-icon fixed-size="N">`)
+
+CSS の `attr()` 関数は数値や `<length>` 型としての解釈をまだ十分にサポートしていないため、
+**`fixed-size` 属性だけではブラウザは hydrate 前にサイズを決定できません**。
+SSR 段階から CLS を防ぐには **必ずインラインスタイルで `--charcoal-icon-size` も同じ値を指定してください**。
+
+```html
+<!-- ✅ OK: fixed-size と --charcoal-icon-size の両方を指定 -->
+<pixiv-icon
+  name="24/Add"
+  fixed-size="12"
+  style="--charcoal-icon-size: 12px;"
 ></pixiv-icon>
+
+<!-- ❌ NG: fixed-size だけだと CSS-only 段階で name 由来の 24px が表示され、
+     JS upgrade 後に 12px へジャンプする (= CLS) -->
+<pixiv-icon name="24/Add" fixed-size="12"></pixiv-icon>
+```
+
+`fixed-size` 属性は Web Component の upgrade 後に **必ず** 反映され、
+`--charcoal-icon-size` インラインスタイルは upgrade 前の CSS-only 状態でサイズを確定させる役割を果たします。
+両者の値が一致していれば、SSR から hydrate 完了までを通じて同じサイズで表示されます。
+
+サーバーサイドのテンプレートで両方を出し分けるユーティリティを用意するか、React の `<Icon fixedSize>` を経由するのが安全です。
+
+#### 非推奨: `unsafe-non-guideline-scale`
+
+過去には `unsafe-non-guideline-scale` 属性でガイドライン外の倍率を指定できましたが、
+これも `fixed-size` と同じ理由で CSS-only 段階ではサイズを決定できません。
+**新規利用は `fixed-size` への移行を推奨します**。
+
+既存利用箇所では、以下のように個別にインラインスタイルでサイズを確定させる必要があります。
+
+```html
 <pixiv-icon
   name="24/Add"
   unsafe-non-guideline-scale="0.5"
-  style="width: 12px; height: 12px;"
+  style="--charcoal-icon-size: 12px;"
 ></pixiv-icon>
 ```

package/src/calcActualSize.ts

@@ -0,0 +1,115 @@
+export type IconSizing =
+  | {
+      scale?: 1 | 2 | 3 | '1' | '2' | '3'
+      /** @deprecated `fixedSize` を利用してください。 */
+      unsafeNonGuidelineScale?: never
+      fixedSize?: never
+    }
+  | {
+      scale?: never
+      /** @deprecated `fixedSize` を利用してください。 */
+      unsafeNonGuidelineScale: number
+      fixedSize?: never
+    }
+  | {
+      scale?: never
+      /** @deprecated `fixedSize` を利用してください。 */
+      unsafeNonGuidelineScale?: never
+      fixedSize: number
+    }
+
+const isPositiveFinite = (value: unknown): value is number =>
+  typeof value === 'number' && Number.isFinite(value) && value > 0
+
+const parseIconName = (name: string): { size: string; baseSize: number } => {
+  if (!name.includes('/')) {
+    throw new TypeError(
+      `"${name}" is not a valid icon name. "name" must be named like [size]/[Name].`,
+    )
+  }
+
+  const [size] = name.split('/')
+
+  if (size === 'Inline') {
+    return { size, baseSize: 16 }
+  }
+
+  const baseSize = parseInt(size, 10)
+  if (Number.isNaN(baseSize) || baseSize <= 0) {
+    throw new TypeError(
+      `"${name}" has invalid size prefix "${size}". Must be "Inline" or a positive number.`,
+    )
+  }
+
+  return { size, baseSize }
+}
+
+function inlineSize(scale: number): number {
+  switch (scale) {
+    case 2:
+      return 32
+    default:
+      return 16
+  }
+}
+
+function guidelineSize24(scale: number): number {
+  return 24 * scale
+}
+
+// fixedSize > unsafeNonGuidelineScale > scale の優先順位で生のサイズを算出する。
+// 戻り値の最終 validation は呼び出し元 (calcActualSize) で行う。
+const resolveSize = ({
+  name,
+  scale,
+  unsafeNonGuidelineScale,
+  fixedSize,
+}: { name: string } & IconSizing): number => {
+  // fixedSize (px 直接指定) が最優先
+  if (isPositiveFinite(fixedSize)) {
+    return fixedSize
+  }
+  if (fixedSize !== undefined) {
+    throw new TypeError(
+      `fixedSize must be a positive finite number, got ${fixedSize}`,
+    )
+  }
+
+  const { size, baseSize } = parseIconName(name)
+
+  // unsafeNonGuidelineScale (deprecated) が次に優先
+  if (isPositiveFinite(unsafeNonGuidelineScale)) {
+    return baseSize * unsafeNonGuidelineScale
+  }
+  if (unsafeNonGuidelineScale !== undefined) {
+    throw new TypeError(
+      `unsafeNonGuidelineScale must be a positive finite number, got ${unsafeNonGuidelineScale}`,
+    )
+  }
+
+  // ガイドライン scale
+  const numericScale = parseInt(`${scale ?? '1'}`, 10)
+  switch (size) {
+    case 'Inline':
+      return inlineSize(numericScale)
+    case '24':
+      return guidelineSize24(numericScale)
+    default:
+      return baseSize
+  }
+}
+
+export const calcActualSize = (
+  params: { name: string } & IconSizing,
+): number => {
+  const actualSize = resolveSize(params)
+
+  // 全 return パスの結果が正の有限数であることを Single Source of Truth として保証する
+  if (!isPositiveFinite(actualSize)) {
+    throw new TypeError(
+      `icon size must be a positive finite number, got ${actualSize}`,
+    )
+  }
+
+  return actualSize
+}

package/src/index.ts

@@ -1,6 +1,7 @@
 import { PixivIcon } from './PixivIcon'
 import { __SERVER__ } from './ssr'
 export { PixivIcon, type KnownIconType, type Props } from './PixivIcon'
+export { calcActualSize, type IconSizing } from './calcActualSize'
 export { KNOWN_ICON_FILES } from './charcoalIconFiles'
 export { PixivIconLoadError } from './loaders/PixivIconLoadError'
 

package/src/react/v1/16/Description.tsx

@@ -0,0 +1,28 @@
+import * as React from 'react'
+import type { SVGProps } from 'react'
+import { Ref, forwardRef } from 'react'
+const SvgDescription = (
+  props: SVGProps<SVGSVGElement>,
+  ref: Ref<SVGSVGElement>,
+) => (
+  <svg
+    width={16}
+    height={16}
+    viewBox="0 0 16 16"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    ref={ref}
+    {...props}
+  >
+    <path
+      fillRule="evenodd"
+      clipRule="evenodd"
+      d="M12.707 5.207a1 1 0 01.293.707V12a2 2 0 01-2 2H5a2 2 0 01-2-2V4a2 2 0 012-2h4.086a1 1 0 01.707.293l2.914 2.914zM6 10a.5.5 0 000 1h4a.5.5 0 000-1H6zm0-2a.5.5 0 000 1h4a.5.5 0 000-1H6zm2.5-2.5a1 1 0 001 1H12L8.5 3v2.5z"
+      fill="currentColor"
+    />
+  </svg>
+)
+export const IconDescription16: ReturnType<
+  typeof React.forwardRef<SVGSVGElement, React.SVGProps<SVGSVGElement>>
+> = forwardRef(SvgDescription)
+export default IconDescription16

package/src/react/v1/index.story.tsx

@@ -11,6 +11,7 @@ import { IconBookmarkOff16 } from './16/BookmarkOff'
 import { IconBookmarkOn16 } from './16/BookmarkOn'
 import { IconCheck16 } from './16/Check'
 import { IconComment16 } from './16/Comment'
+import { IconDescription16 } from './16/Description'
 import { IconDot16 } from './16/Dot'
 import { IconDown16 } from './16/Down'
 import { IconError16 } from './16/Error'
@@ -632,6 +633,11 @@ export default {
             <code>&lt;IconDelete32 /&gt;</code>
           </div>
 
+          <div>
+            <IconDescription16 />
+            <code>&lt;IconDescription16 /&gt;</code>
+          </div>
+
           <div>
             <IconDescription24 />
             <code>&lt;IconDescription24 /&gt;</code>

package/src/react/v1/index.tsx

@@ -8,6 +8,7 @@ export { IconBookmarkOff16 } from './16/BookmarkOff'
 export { IconBookmarkOn16 } from './16/BookmarkOn'
 export { IconCheck16 } from './16/Check'
 export { IconComment16 } from './16/Comment'
+export { IconDescription16 } from './16/Description'
 export { IconDot16 } from './16/Dot'
 export { IconDown16 } from './16/Down'
 export { IconError16 } from './16/Error'