カタログファイル
コンポーネントの隣に <Name>.zukan.svelte を置きます。<Name>.zukan.md は任意です。zukan/ のような専用のディレクトリは要りません。ファイル名はどのプラットフォームでも大文字と小文字を区別して照合するので、Button.Zukan.svelte はカタログファイルになりません。Button.Zukan.md と button.svelte も Button.zukan.svelte の .md やコンポーネントとしては読みません。
src/lib/Button/
├── Button.svelte
├── Button.zukan.svelte
└── Button.zukan.md
セクション
カタログファイルは <Section> を並べた Svelte コンポーネントです。セクション 1 つが 1 つの例で、それぞれ別々にプレビューします。
<!-- src/lib/Button/Button.zukan.svelte -->
<script lang="ts">
import { Section } from 'svelte-zukan';
import Button from './Button.svelte';
let count = $state(0);
const label = $derived(`${count} clicks`);
</script>
<Section title="Basic">
<Button onclick={() => count++}>{label}</Button>
</Section>
<Section title="Disabled">
<Button disabled>Disabled</Button>
</Section>
<Section>はトップレベル(他の要素やブロックの中ではない位置)に置きますtitleは空でない静的な文字列で、同じファイル内で重複できません- マークアップと
<script>は素の Svelte で書きます(lang="ts"の TypeScript は使えます)。SCSS などのプリプロセッサの言語は<style>の中でだけ使えます
title がない、動的、空、同じファイル内で重複している場合と、<Section> がトップレベルにない場合は、どれもファイル名と行つきのビルドエラーになります。素の Svelte として読めないファイルも、ファイル名つきのビルドエラーになります。dev サーバーでは、代わりにそのファイルの詳細ページに同じメッセージが出て、アプリのタブには何も出ません。ただし、アプリのページがそのファイルを import しているときは、いつもどおりそのタブにも Vite のエラーが出ます。
Svelte のコンパイラーが出すエラーや解決できない import など、カタログファイルのそのほかのエラーは、ターミナルと、dev サーバーではそのファイルのプレビューに出ます。カタログファイルからだけ import されているファイルのエラーも同じです。こちらも、アプリがそのファイルを import していない限りアプリのタブには何も出ず、ファイルを直すとプレビューが再読み込みされます。
<Section> が 1 つもないファイルはエラーになりません。詳細ページに、プレビューするものがないと表示します。中身のない <Section> は何も表示しません。
コード表示
詳細ページは各セクションの中身を構文ごとに色分けしたコードで示し、そのセクションが参照している <script> 内の定義も合わせて載せます。上の例では「Basic」のコードに label と count も出ます。セクションが使うトップレベルの {#snippet}、<script module> 内の宣言、TypeScript の型も載せます。Section は import { Section as Example } from 'svelte-zukan' のように別名で import しても、import * as Z from 'svelte-zukan' で名前空間ごと import して <Z.Section> と書いても使えます。
Markdown の説明
Button.zukan.md は同じディレクトリにある Button.zukan.svelte だけに対応します。このファイルがあれば、詳細ページの上部に HTML として表示します。.md 内の生の HTML も含めてそのまま挿入するので、カタログを公開する前に .md もコードと同じようにレビューしてください。
<!-- src/lib/Button/Button.zukan.md -->
A button for the main action on a page. Use one per screen.
Props の一覧
Button.zukan.svelte の隣に Button.svelte があれば、詳細ページの説明の下、セクションの上に、その props の一覧を出します。一覧には名前、型、デフォルト値、JSDoc コメントが並びます。JSDoc コメントは最初の @ タグの手前までを、インラインの Markdown として表示します。コードブロック内の @ で始まる行はコードであり、タグとして扱いません。エディターと同じく、コメント中の HTML は文字のまま表示し、{@link} は名前ならコード、http や https の URL ならリンクとして表示します。型に JSDoc コメントがない props には、分割代入に書いた JSDoc コメント(let { /** … */ children })を使います。パッケージの型から来る props の説明は、ここに書きます。? もデフォルト値もない props には「必須」、デフォルト値が $bindable() の props には「バインド可能」と付きます。
<!-- src/lib/Button/Button.svelte -->
<script lang="ts">
import type { HTMLButtonAttributes } from 'svelte/elements';
let {
variant = 'primary',
disabled = false,
children,
...rest
}: HTMLButtonAttributes & {
/** the look of the button: `primary` for the main action */
variant?: 'primary' | 'secondary';
disabled?: boolean;
} = $props();
</script>
<button class={variant} {disabled} {...rest}>
{@render children?.()}
</button>
props はコンポーネントを実行せず、ソースを読んで取り出します。型はその場に書いても、コンポーネント内で宣言した type エイリアスや interface(interface の extends を含む)でもかまいません。型を書く場所は、分割代入でも $props() 自体(let { a } = $props() as Props、または satisfies)でもかまいません。interface が extends した型のメンバーを絞り込んだときのように、同じ名前の prop が 2 回宣言されていれば、その interface 自身の宣言で 1 行だけ並びます。1 つのファイルで 2 回宣言した interface は、両方の宣言のメンバーが並びます。相対パスで import した型も読みます。.ts や .d.ts のファイル(./types、./types.js、./types/index.ts、./types/index.d.ts。export … from による再エクスポートや、export { Inner as Props } のように別の名前で export した型も含む)、.svelte.ts のモジュール(./state.svelte)、ほかのコンポーネントの <script module> から import した型で、import は 7 ファイル先までたどります。Vite の resolve.alias を通るパスも同じように読むので、SvelteKit の設定に alias: { $lib: 'src/lib' } があれば、$lib/utils.js はプロジェクト内のファイルとして扱います。パッケージ名や node_modules の中を指す alias は、そのパッケージとして読みます。いちばん近い package.json の imports によるサブパス import(SvelteKit の #lib/utils.js など)も同じように読みます。package.json 自体を編集しても一覧は更新されません。名前を指定した import のほか、default export(export default interface Props)や名前空間でも読みます。名前空間は import と export のどちらの側でもかまいません。import type * as T での T.Props も、export * as P from './p' と書いたファイルの P.Props(bits-ui の Accordion.TriggerProps など)も読みます。ジェネリックな type エイリアスや interface は、渡した型引数(省略したものはデフォルト)で読みます。type WithElementRef<T, U extends HTMLElement = HTMLElement> = T & { ref?: U | null } なら、WithElementRef<HTMLButtonAttributes, HTMLButtonElement> の ref は HTMLButtonElement | null と並び、HTMLButtonAttributes は名前で示します。パッケージのジェネリックな型も同じように読むので、HTMLAttributes<HTMLDivElement> の onclick には HTMLDivElement が出ます。デフォルトの型で必ず成り立つ条件(Slots extends { _default: never } ? Snippet : Snippet<[Slots]>)は Snippet と出ます。リテラルのキーか、一覧にできる型の keyof を指定した Omit と Pick(Omit<Base, 'id' | 'class'>、Omit<Base, keyof Own>)は、残るメンバーを並べます。T extends { child?: any } ? Omit<T, 'child'> : T のようにキーを除くだけの条件型も同じです。元の型のメンバーをすべて一覧にできないときは、名前でも出します。パッケージの型に対しては、パッケージの型と同じく、残るメンバーのうち分割代入したものだけを並べます。パッケージの型(svelte/elements の HTMLButtonAttributes など)は、一覧の上に型の名前を出します。複数あるときはカンマで区切って出します。そのメンバーのうち一覧に並ぶのは分割代入した props だけで、型と JSDoc コメントは、パッケージの型のファイル(exports の types 条件、exports が指す JavaScript ファイルの隣にある .d.ts、types フィールドが指すもの、または main の隣にある .d.ts。.d.ts のほか、ワークスペースのパッケージならソースの .ts、.mts、.cts でもかまいません。exports のないパッケージのサブパスなら sub.d.ts か sub/index.d.ts)から読みます。パッケージ自身に型がなければ @types/<name> から読みます。typesVersions は読みません。上の例の children は Snippet になります。...rest に入るものは並びません。svelte-package でビルドしたライブラリのコンポーネントは、隣にある Button.svelte.d.ts から読みます。そのファイルが export する Props の型も、ComponentProps<typeof Button>(svelte の ComponentProps)も同じです。プロジェクト内のコンポーネント(import Field from './Field.svelte')の ComponentProps<typeof Field> は、その $props() の型を読みます。ユニオン型({ href: string } | { onclick: () => void })のように読めない型は、一覧にその型を書かれたとおりに出し、その型で受け取るはずの分割代入した props は型なしで並びます。props の型を書いたプロジェクト内のファイルを編集、作成、削除すると、alias の先のファイルでも一覧が更新されます。node_modules の外からリンクされたワークスペースのパッケージの型を編集したときも同じです。パースできないコンポーネントや $props() のないコンポーネントには、一覧を出しません。JSDoc コメントの Markdown のリンクと画像は HTML になるので、カタログを公開する前にコードと同じようにレビューしてください。
接尾辞を変える
接尾辞は suffix オプションで変えられます。zukan({ suffix: 'catalog' }) なら *.catalog.svelte と *.catalog.md になります。
監視と HMR
- カタログファイルや
.mdを作成・削除・編集すると、/__zukan/のタブだけが再読み込みされます。同じ dev サーバーにつないだアプリのタブは再読み込みされません。カタログファイルを import しているアプリのページには、通常の HMR で編集が反映されます logoの画像を編集したときも、/__zukan/のタブだけが再読み込みされます- コンポーネント本体(
Button.svelteなど)を編集すると、通常の HMR でアプリとカタログの両方に反映されます。props が変わる編集のときは、props の一覧を更新するために/__zukan/のタブも再読み込みされます - Vite の root の外にあるディレクトリ(モノレポの別パッケージなど)も監視します