docs(vue): add interactive demo for every composable
A beautiful, SSR-safe demo.vue next to each composable, auto-discovered by the docs extractor and rendered client-only on each composable's page.
This commit is contained in:
@@ -0,0 +1,104 @@
|
||||
<script setup lang="ts">
|
||||
import { computed } from 'vue';
|
||||
import { useLocalStorage } from './index';
|
||||
|
||||
// Persists across reloads and syncs across tabs via the `storage` event.
|
||||
const username = useLocalStorage('demo:username', 'ada-lovelace');
|
||||
const fontSize = useLocalStorage('demo:font-size', 16);
|
||||
const darkMode = useLocalStorage('demo:dark-mode', false);
|
||||
|
||||
// Object value — serialized as JSON automatically.
|
||||
const profile = useLocalStorage('demo:profile', {
|
||||
role: 'Engineer',
|
||||
team: 'Platform',
|
||||
});
|
||||
|
||||
const persistedJson = computed(() =>
|
||||
JSON.stringify(
|
||||
{ username: username.value, fontSize: fontSize.value, darkMode: darkMode.value, profile: profile.value },
|
||||
null,
|
||||
2,
|
||||
),
|
||||
);
|
||||
|
||||
function reset() {
|
||||
// Assigning null removes the key; the ref falls back to its default on next read.
|
||||
username.value = null as never;
|
||||
fontSize.value = 16;
|
||||
darkMode.value = false;
|
||||
profile.value = { role: 'Engineer', team: 'Platform' };
|
||||
}
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<div class="w-full max-w-sm flex flex-col gap-4">
|
||||
<div class="flex items-center justify-between">
|
||||
<span class="text-xs font-medium uppercase tracking-wide text-(--fg-subtle)">Persisted settings</span>
|
||||
<span class="inline-flex items-center gap-1.5 rounded-md border border-(--border) bg-(--bg-inset) px-2 py-0.5 text-xs font-medium text-(--fg-muted)">
|
||||
localStorage
|
||||
</span>
|
||||
</div>
|
||||
|
||||
<div class="rounded-xl border border-(--border) bg-(--bg-elevated) p-4 flex flex-col gap-4">
|
||||
<label class="flex flex-col gap-1.5">
|
||||
<span class="text-xs font-medium uppercase tracking-wide text-(--fg-subtle)">Username</span>
|
||||
<input
|
||||
v-model="username"
|
||||
type="text"
|
||||
placeholder="your handle"
|
||||
class="w-full rounded-lg border border-(--border) bg-(--bg) px-3 py-2 text-sm text-(--fg) placeholder:text-(--fg-subtle) transition focus:border-(--accent) focus:outline-none focus:ring-2 focus:ring-(--ring)"
|
||||
>
|
||||
</label>
|
||||
|
||||
<label class="flex flex-col gap-1.5">
|
||||
<div class="flex items-center justify-between">
|
||||
<span class="text-xs font-medium uppercase tracking-wide text-(--fg-subtle)">Font size</span>
|
||||
<span class="font-mono text-sm tabular-nums text-(--fg-muted)">{{ fontSize }}px</span>
|
||||
</div>
|
||||
<input
|
||||
v-model.number="fontSize"
|
||||
type="range"
|
||||
min="12"
|
||||
max="28"
|
||||
step="1"
|
||||
class="w-full accent-(--accent)"
|
||||
>
|
||||
</label>
|
||||
|
||||
<button
|
||||
type="button"
|
||||
:aria-pressed="darkMode"
|
||||
class="flex items-center justify-between rounded-lg border border-(--border) bg-(--bg-inset) px-3 py-2 text-sm font-medium text-(--fg) transition hover:border-(--border-strong) cursor-pointer"
|
||||
@click="darkMode = !darkMode"
|
||||
>
|
||||
<span>Dark mode</span>
|
||||
<span
|
||||
class="relative h-5 w-9 rounded-full transition"
|
||||
:class="darkMode ? 'bg-(--accent)' : 'bg-(--border-strong)'"
|
||||
>
|
||||
<span
|
||||
class="absolute top-0.5 h-4 w-4 rounded-full bg-white transition-all"
|
||||
:class="darkMode ? 'left-4' : 'left-0.5'"
|
||||
/>
|
||||
</span>
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<pre
|
||||
class="rounded-lg border border-(--border) bg-(--bg-inset) p-3 font-mono text-xs leading-relaxed text-(--fg) overflow-auto"
|
||||
:style="{ fontSize: `${fontSize}px` }"
|
||||
>{{ persistedJson }}</pre>
|
||||
|
||||
<p class="text-xs text-(--fg-subtle)">
|
||||
Edit anything, then reload the page or open a second tab — values stay in sync.
|
||||
</p>
|
||||
|
||||
<button
|
||||
type="button"
|
||||
class="inline-flex items-center justify-center gap-1.5 rounded-lg border border-(--border) bg-(--bg-elevated) px-3 py-1.5 text-sm font-medium text-(--fg) transition hover:bg-(--bg-inset) hover:border-(--border-strong) active:scale-[0.98] cursor-pointer"
|
||||
@click="reset"
|
||||
>
|
||||
Reset to defaults
|
||||
</button>
|
||||
</div>
|
||||
</template>
|
||||
@@ -0,0 +1,121 @@
|
||||
<script setup lang="ts">
|
||||
import { computed } from 'vue';
|
||||
import { useSessionStorage } from './index';
|
||||
|
||||
// sessionStorage survives reloads but is cleared when the tab closes —
|
||||
// perfect for a multi-step draft that should not leak between sessions.
|
||||
const step = useSessionStorage('demo:wizard-step', 1);
|
||||
|
||||
const draft = useSessionStorage('demo:wizard-draft', {
|
||||
name: '',
|
||||
email: '',
|
||||
newsletter: true,
|
||||
});
|
||||
|
||||
const totalSteps = 3;
|
||||
|
||||
const progress = computed(() => Math.round((step.value / totalSteps) * 100));
|
||||
|
||||
function next() {
|
||||
if (step.value < totalSteps)
|
||||
step.value++;
|
||||
}
|
||||
|
||||
function prev() {
|
||||
if (step.value > 1)
|
||||
step.value--;
|
||||
}
|
||||
|
||||
function clearDraft() {
|
||||
step.value = 1;
|
||||
draft.value = { name: '', email: '', newsletter: true };
|
||||
}
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<div class="w-full max-w-sm flex flex-col gap-4">
|
||||
<div class="flex items-center justify-between">
|
||||
<span class="text-xs font-medium uppercase tracking-wide text-(--fg-subtle)">
|
||||
Step {{ step }} of {{ totalSteps }}
|
||||
</span>
|
||||
<span class="inline-flex items-center gap-1.5 rounded-md border border-(--border) bg-(--bg-inset) px-2 py-0.5 text-xs font-medium text-(--fg-muted)">
|
||||
sessionStorage
|
||||
</span>
|
||||
</div>
|
||||
|
||||
<div class="h-1.5 w-full overflow-hidden rounded-full bg-(--bg-inset)">
|
||||
<div
|
||||
class="h-full rounded-full bg-(--accent) transition-all duration-300"
|
||||
:style="{ width: `${progress}%` }"
|
||||
/>
|
||||
</div>
|
||||
|
||||
<div class="rounded-xl border border-(--border) bg-(--bg-elevated) p-4 flex flex-col gap-4">
|
||||
<template v-if="step === 1">
|
||||
<label class="flex flex-col gap-1.5">
|
||||
<span class="text-xs font-medium uppercase tracking-wide text-(--fg-subtle)">Full name</span>
|
||||
<input
|
||||
v-model="draft.name"
|
||||
type="text"
|
||||
placeholder="Grace Hopper"
|
||||
class="w-full rounded-lg border border-(--border) bg-(--bg) px-3 py-2 text-sm text-(--fg) placeholder:text-(--fg-subtle) transition focus:border-(--accent) focus:outline-none focus:ring-2 focus:ring-(--ring)"
|
||||
>
|
||||
</label>
|
||||
</template>
|
||||
|
||||
<template v-else-if="step === 2">
|
||||
<label class="flex flex-col gap-1.5">
|
||||
<span class="text-xs font-medium uppercase tracking-wide text-(--fg-subtle)">Email</span>
|
||||
<input
|
||||
v-model="draft.email"
|
||||
type="email"
|
||||
placeholder="grace@navy.mil"
|
||||
class="w-full rounded-lg border border-(--border) bg-(--bg) px-3 py-2 text-sm text-(--fg) placeholder:text-(--fg-subtle) transition focus:border-(--accent) focus:outline-none focus:ring-2 focus:ring-(--ring)"
|
||||
>
|
||||
</label>
|
||||
</template>
|
||||
|
||||
<template v-else>
|
||||
<label class="flex items-center justify-between gap-3 cursor-pointer">
|
||||
<span class="text-sm text-(--fg)">Subscribe to the newsletter</span>
|
||||
<input v-model="draft.newsletter" type="checkbox" class="h-4 w-4 accent-(--accent)">
|
||||
</label>
|
||||
<div class="rounded-lg border border-(--border) bg-(--bg-inset) p-3 text-sm text-(--fg-muted)">
|
||||
<p><span class="text-(--fg-subtle)">Name:</span> {{ draft.name || '—' }}</p>
|
||||
<p><span class="text-(--fg-subtle)">Email:</span> {{ draft.email || '—' }}</p>
|
||||
</div>
|
||||
</template>
|
||||
</div>
|
||||
|
||||
<div class="flex items-center gap-2">
|
||||
<button
|
||||
type="button"
|
||||
:disabled="step === 1"
|
||||
class="inline-flex flex-1 items-center justify-center gap-1.5 rounded-lg border border-(--border) bg-(--bg-elevated) px-3 py-1.5 text-sm font-medium text-(--fg) transition hover:bg-(--bg-inset) hover:border-(--border-strong) active:scale-[0.98] cursor-pointer disabled:cursor-not-allowed disabled:opacity-40 disabled:active:scale-100"
|
||||
@click="prev"
|
||||
>
|
||||
Back
|
||||
</button>
|
||||
<button
|
||||
type="button"
|
||||
:disabled="step === totalSteps"
|
||||
class="inline-flex flex-1 items-center justify-center gap-1.5 rounded-lg border border-transparent bg-(--accent) px-3 py-1.5 text-sm font-medium text-(--accent-fg) transition hover:bg-(--accent-hover) active:scale-[0.98] cursor-pointer disabled:cursor-not-allowed disabled:opacity-40 disabled:active:scale-100"
|
||||
@click="next"
|
||||
>
|
||||
Continue
|
||||
</button>
|
||||
</div>
|
||||
|
||||
<p class="text-xs text-(--fg-subtle)">
|
||||
Reload the page — your step and draft are restored. Closing the tab clears them.
|
||||
</p>
|
||||
|
||||
<button
|
||||
type="button"
|
||||
class="self-start text-xs font-medium text-(--fg-muted) underline-offset-2 hover:underline cursor-pointer"
|
||||
@click="clearDraft"
|
||||
>
|
||||
Discard draft
|
||||
</button>
|
||||
</div>
|
||||
</template>
|
||||
@@ -0,0 +1,130 @@
|
||||
<script setup lang="ts">
|
||||
import { computed, reactive } from 'vue';
|
||||
import { useStorage } from './index';
|
||||
import type { StorageLike } from './index';
|
||||
|
||||
// useStorage is backend-agnostic: pass any object implementing StorageLike.
|
||||
// Here we use a transparent in-memory backend so the demo is fully SSR-safe
|
||||
// and we can show exactly what gets written to the store.
|
||||
const raw = reactive<Record<string, string>>({});
|
||||
|
||||
const memoryStorage: StorageLike = {
|
||||
getItem: (key) => (key in raw ? raw[key] : null),
|
||||
setItem: (key, value) => { raw[key] = value; },
|
||||
removeItem: (key) => { delete raw[key]; },
|
||||
};
|
||||
|
||||
// A Set value — useStorage guesses the Set serializer automatically.
|
||||
const tags = useStorage('demo:tags', new Set(['vue', 'reactive']), memoryStorage);
|
||||
|
||||
// A custom serializer: store a number as a zero-padded string.
|
||||
const ticket = useStorage('demo:ticket', 1, memoryStorage, {
|
||||
serializer: {
|
||||
read: (v) => Number.parseInt(v, 10),
|
||||
write: (v) => String(v).padStart(5, '0'),
|
||||
},
|
||||
});
|
||||
|
||||
const newTag = reactive({ value: '' });
|
||||
|
||||
const tagList = computed(() => [...tags.value]);
|
||||
const storeEntries = computed(() => Object.entries(raw));
|
||||
|
||||
function addTag() {
|
||||
const t = newTag.value.trim().toLowerCase();
|
||||
if (!t)
|
||||
return;
|
||||
// Reassign so the shallowRef watcher fires and writes to storage.
|
||||
tags.value = new Set([...tags.value, t]);
|
||||
newTag.value = '';
|
||||
}
|
||||
|
||||
function removeTag(tag: string) {
|
||||
const next = new Set(tags.value);
|
||||
next.delete(tag);
|
||||
tags.value = next;
|
||||
}
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<div class="w-full max-w-sm flex flex-col gap-4">
|
||||
<div class="flex items-center justify-between">
|
||||
<span class="text-xs font-medium uppercase tracking-wide text-(--fg-subtle)">Custom storage backend</span>
|
||||
<span class="inline-flex items-center gap-1.5 rounded-md border border-(--border) bg-(--bg-inset) px-2 py-0.5 text-xs font-medium text-(--fg-muted)">
|
||||
in-memory
|
||||
</span>
|
||||
</div>
|
||||
|
||||
<div class="rounded-xl border border-(--border) bg-(--bg-elevated) p-4 flex flex-col gap-3">
|
||||
<span class="text-xs font-medium uppercase tracking-wide text-(--fg-subtle)">Tags (Set)</span>
|
||||
|
||||
<div class="flex flex-wrap gap-1.5 min-h-7">
|
||||
<span
|
||||
v-for="tag in tagList"
|
||||
:key="tag"
|
||||
class="inline-flex items-center gap-1.5 rounded-md border border-(--border) bg-(--bg-inset) px-2 py-0.5 text-xs font-medium text-(--fg-muted)"
|
||||
>
|
||||
{{ tag }}
|
||||
<button
|
||||
type="button"
|
||||
class="text-(--fg-subtle) transition hover:text-(--fg) cursor-pointer"
|
||||
:aria-label="`Remove ${tag}`"
|
||||
@click="removeTag(tag)"
|
||||
>
|
||||
×
|
||||
</button>
|
||||
</span>
|
||||
<span v-if="tagList.length === 0" class="text-xs text-(--fg-subtle)">No tags yet</span>
|
||||
</div>
|
||||
|
||||
<form class="flex items-center gap-2" @submit.prevent="addTag">
|
||||
<input
|
||||
v-model="newTag.value"
|
||||
type="text"
|
||||
placeholder="add a tag…"
|
||||
class="w-full rounded-lg border border-(--border) bg-(--bg) px-3 py-2 text-sm text-(--fg) placeholder:text-(--fg-subtle) transition focus:border-(--accent) focus:outline-none focus:ring-2 focus:ring-(--ring)"
|
||||
>
|
||||
<button
|
||||
type="submit"
|
||||
class="inline-flex items-center justify-center gap-1.5 rounded-lg border border-transparent bg-(--accent) px-3 py-1.5 text-sm font-medium text-(--accent-fg) transition hover:bg-(--accent-hover) active:scale-[0.98] cursor-pointer"
|
||||
>
|
||||
Add
|
||||
</button>
|
||||
</form>
|
||||
</div>
|
||||
|
||||
<div class="rounded-xl border border-(--border) bg-(--bg-elevated) p-4 flex items-center justify-between">
|
||||
<div class="flex flex-col gap-0.5">
|
||||
<span class="text-xs font-medium uppercase tracking-wide text-(--fg-subtle)">Ticket #</span>
|
||||
<span class="text-xs text-(--fg-subtle)">zero-padded serializer</span>
|
||||
</div>
|
||||
<div class="flex items-center gap-3">
|
||||
<button
|
||||
type="button"
|
||||
class="inline-flex h-8 w-8 items-center justify-center rounded-lg border border-(--border) bg-(--bg-inset) text-(--fg) transition hover:border-(--border-strong) active:scale-[0.98] cursor-pointer"
|
||||
@click="ticket = Math.max(0, ticket - 1)"
|
||||
>
|
||||
−
|
||||
</button>
|
||||
<span class="font-mono text-2xl font-bold tabular-nums text-(--fg)">{{ ticket }}</span>
|
||||
<button
|
||||
type="button"
|
||||
class="inline-flex h-8 w-8 items-center justify-center rounded-lg border border-(--border) bg-(--bg-inset) text-(--fg) transition hover:border-(--border-strong) active:scale-[0.98] cursor-pointer"
|
||||
@click="ticket = ticket + 1"
|
||||
>
|
||||
+
|
||||
</button>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="flex flex-col gap-1.5">
|
||||
<span class="text-xs font-medium uppercase tracking-wide text-(--fg-subtle)">Raw store contents</span>
|
||||
<div class="rounded-lg border border-(--border) bg-(--bg-inset) p-3 font-mono text-xs text-(--fg) flex flex-col gap-1">
|
||||
<div v-for="[key, value] in storeEntries" :key="key" class="flex gap-2">
|
||||
<span class="text-(--fg-subtle) shrink-0">{{ key }}</span>
|
||||
<span class="truncate">{{ value }}</span>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</template>
|
||||
@@ -0,0 +1,124 @@
|
||||
<script setup lang="ts">
|
||||
import { reactive, ref } from 'vue';
|
||||
import { useStorageAsync } from './index';
|
||||
import type { StorageLikeAsync } from './index';
|
||||
|
||||
// useStorageAsync works with any async backend (IndexedDB, a REST cache, etc.).
|
||||
// We simulate latency with a tiny in-memory store so the demo is SSR-safe and
|
||||
// you can watch the `isReady` flag flip once the initial read resolves.
|
||||
const store = reactive<Record<string, string>>({});
|
||||
const LATENCY = 600;
|
||||
|
||||
function delay<T>(value: T): Promise<T> {
|
||||
return new Promise((resolve) => { setTimeout(() => resolve(value), LATENCY); });
|
||||
}
|
||||
|
||||
const asyncStorage: StorageLikeAsync = {
|
||||
getItem: (key) => delay(key in store ? store[key] : null),
|
||||
setItem: async (key, value) => { await delay(null); store[key] = value; },
|
||||
removeItem: async (key) => { await delay(null); delete store[key]; },
|
||||
};
|
||||
|
||||
const saving = ref(false);
|
||||
|
||||
// Returns { state, isReady } and is itself awaitable. `isReady` flips to true
|
||||
// once the initial async read resolves — the composable sets it for us.
|
||||
const { state: prefs, isReady } = useStorageAsync(
|
||||
'demo:async-prefs',
|
||||
{ theme: 'system', density: 'comfortable' },
|
||||
asyncStorage,
|
||||
);
|
||||
|
||||
const themes = ['light', 'dark', 'system'] as const;
|
||||
const densities = ['compact', 'comfortable'] as const;
|
||||
|
||||
async function update<K extends keyof typeof prefs.value>(key: K, value: (typeof prefs.value)[K]) {
|
||||
prefs.value = { ...prefs.value, [key]: value };
|
||||
// The watcher writes asynchronously; show a brief saving indicator.
|
||||
saving.value = true;
|
||||
await delay(null);
|
||||
saving.value = false;
|
||||
}
|
||||
</script>
|
||||
|
||||
<template>
|
||||
<div class="w-full max-w-sm flex flex-col gap-4">
|
||||
<div class="flex items-center justify-between">
|
||||
<span class="text-xs font-medium uppercase tracking-wide text-(--fg-subtle)">Async preferences</span>
|
||||
<span
|
||||
class="inline-flex items-center gap-1.5 rounded-md border px-2 py-0.5 text-xs font-medium transition"
|
||||
:class="isReady
|
||||
? 'border-emerald-500/30 bg-emerald-500/10 text-emerald-600 dark:text-emerald-400'
|
||||
: 'border-(--border) bg-(--bg-inset) text-(--fg-muted)'"
|
||||
>
|
||||
<span
|
||||
class="h-1.5 w-1.5 rounded-full"
|
||||
:class="isReady ? 'bg-emerald-500' : 'bg-(--fg-subtle) animate-pulse'"
|
||||
/>
|
||||
{{ isReady ? 'ready' : 'loading…' }}
|
||||
</span>
|
||||
</div>
|
||||
|
||||
<div
|
||||
v-if="!isReady"
|
||||
class="rounded-xl border border-(--border) bg-(--bg-elevated) p-4 flex flex-col gap-3"
|
||||
>
|
||||
<div class="h-3 w-1/3 animate-pulse rounded bg-(--bg-inset)" />
|
||||
<div class="h-9 w-full animate-pulse rounded-lg bg-(--bg-inset)" />
|
||||
<div class="h-3 w-1/3 animate-pulse rounded bg-(--bg-inset)" />
|
||||
<div class="h-9 w-full animate-pulse rounded-lg bg-(--bg-inset)" />
|
||||
</div>
|
||||
|
||||
<div v-else class="rounded-xl border border-(--border) bg-(--bg-elevated) p-4 flex flex-col gap-4">
|
||||
<div class="flex flex-col gap-2">
|
||||
<span class="text-xs font-medium uppercase tracking-wide text-(--fg-subtle)">Theme</span>
|
||||
<div class="grid grid-cols-3 gap-1.5">
|
||||
<button
|
||||
v-for="t in themes"
|
||||
:key="t"
|
||||
type="button"
|
||||
class="rounded-lg border px-2 py-1.5 text-sm font-medium capitalize transition active:scale-[0.98] cursor-pointer"
|
||||
:class="prefs.theme === t
|
||||
? 'border-transparent bg-(--accent) text-(--accent-fg)'
|
||||
: 'border-(--border) bg-(--bg-inset) text-(--fg) hover:border-(--border-strong)'"
|
||||
@click="update('theme', t)"
|
||||
>
|
||||
{{ t }}
|
||||
</button>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="flex flex-col gap-2">
|
||||
<span class="text-xs font-medium uppercase tracking-wide text-(--fg-subtle)">Density</span>
|
||||
<div class="grid grid-cols-2 gap-1.5">
|
||||
<button
|
||||
v-for="d in densities"
|
||||
:key="d"
|
||||
type="button"
|
||||
class="rounded-lg border px-2 py-1.5 text-sm font-medium capitalize transition active:scale-[0.98] cursor-pointer"
|
||||
:class="prefs.density === d
|
||||
? 'border-transparent bg-(--accent) text-(--accent-fg)'
|
||||
: 'border-(--border) bg-(--bg-inset) text-(--fg) hover:border-(--border-strong)'"
|
||||
@click="update('density', d)"
|
||||
>
|
||||
{{ d }}
|
||||
</button>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
|
||||
<div class="rounded-lg border border-(--border) bg-(--bg-inset) p-3 font-mono text-sm text-(--fg) flex items-center justify-between">
|
||||
<span class="truncate">{{ JSON.stringify(prefs) }}</span>
|
||||
<span
|
||||
class="ml-2 shrink-0 text-xs transition"
|
||||
:class="saving ? 'text-sky-600 dark:text-sky-400' : 'text-(--fg-subtle)'"
|
||||
>
|
||||
{{ saving ? 'saving…' : 'saved' }}
|
||||
</span>
|
||||
</div>
|
||||
|
||||
<p class="text-xs text-(--fg-subtle)">
|
||||
Every change is written through the async backend with simulated latency.
|
||||
</p>
|
||||
</div>
|
||||
</template>
|
||||
Reference in New Issue
Block a user