You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
1099 lines
36 KiB
1099 lines
36 KiB
<script lang="ts">
|
|
import {
|
|
Image,
|
|
type ImageFit,
|
|
type ImagePosition,
|
|
type ImageRadius,
|
|
type ImageSize,
|
|
type ImagePlaceholder,
|
|
type ImagePlaceholderColor,
|
|
type ImageStatusValue
|
|
} from '$uix/eidos/components/image';
|
|
import { AspectRatio } from '$uix/eidos/components/aspect-ratio';
|
|
import { compileMorfo } from '$uix/morfo';
|
|
import { imageMorfo } from '@/uix/morfo/components/image';
|
|
|
|
type Tab = 'live' | 'api' | 'morfo' | 'sema' | 'recipe' | 'a11y';
|
|
type TraceEntry = { event: string; family: string; intent?: string; at: number };
|
|
let tab = $state<Tab>('live');
|
|
let trace = $state<TraceEntry[]>([]);
|
|
let stageRef = $state<HTMLElement | null>(null);
|
|
|
|
// ── Live state ────────────────────────────────────────────────────────
|
|
let src = $state<string>('https://picsum.photos/seed/uix-image/640/360');
|
|
let alt = $state('A photographic landscape from Lorem Picsum');
|
|
let fit = $state<ImageFit>('cover');
|
|
let position = $state<ImagePosition>('center');
|
|
let radius = $state<ImageRadius>('md');
|
|
let size = $state<ImageSize | ''>('lg');
|
|
let placeholder = $state<ImagePlaceholder>('skeleton');
|
|
let placeholderColor = $state<ImagePlaceholderColor>('neutral');
|
|
let delayMs = $state(0);
|
|
let loading = $state<'lazy' | 'eager'>('lazy');
|
|
let breakImage = $state(false);
|
|
let imageStatus = $state<ImageStatusValue>('idle');
|
|
|
|
const effectiveSrc = $derived(breakImage ? 'https://broken.invalid/x.png' : src);
|
|
|
|
function reload() {
|
|
// Force a re-fetch by tagging the URL with a fresh nonce.
|
|
const base = src.split('?')[0];
|
|
src = `${base}?n=${Date.now()}`;
|
|
}
|
|
|
|
// ── Compiled morfo ────────────────────────────────────────────────────
|
|
const compiled = compileMorfo(imageMorfo);
|
|
const partsList = $derived([...compiled.parts.byKebab.values()]);
|
|
const events = $derived([...compiled.actions.byName.values()]);
|
|
|
|
$effect(() => {
|
|
const el = stageRef;
|
|
if (!el) return;
|
|
const obs = new MutationObserver((mutations) => {
|
|
for (const m of mutations) {
|
|
if (m.attributeName !== 'data-event') continue;
|
|
const target = m.target as Element;
|
|
const ev = target.getAttribute('data-event');
|
|
if (!ev) continue;
|
|
trace = [
|
|
{
|
|
event: ev,
|
|
family: target.getAttribute('data-event-family') ?? '—',
|
|
intent: target.getAttribute('data-event-intent') ?? undefined,
|
|
at: Date.now()
|
|
},
|
|
...trace
|
|
].slice(0, 6);
|
|
}
|
|
});
|
|
obs.observe(el, { attributes: true, subtree: true, attributeFilter: ['data-event'] });
|
|
return () => obs.disconnect();
|
|
});
|
|
|
|
const eidosSnippet = $derived(
|
|
[
|
|
"<script lang='ts'>",
|
|
" import { Image } from '$uix/eidos/components/image';",
|
|
'</' + 'script>',
|
|
'',
|
|
'<Image',
|
|
` src="${effectiveSrc}"`,
|
|
` alt="${alt}"`,
|
|
fit !== 'cover' && ` fit="${fit}"`,
|
|
position !== 'center' && ` position="${position}"`,
|
|
radius !== 'none' && ` radius="${radius}"`,
|
|
size !== '' && ` size="${size}"`,
|
|
placeholder !== 'skeleton' && ` placeholder="${placeholder}"`,
|
|
placeholder === 'color' &&
|
|
placeholderColor !== 'neutral' &&
|
|
` placeholderColor="${placeholderColor}"`,
|
|
delayMs > 0 && ` delayMs={${delayMs}}`,
|
|
loading !== 'lazy' && ` loading="${loading}"`,
|
|
'/>'
|
|
]
|
|
.filter(Boolean)
|
|
.join('\n')
|
|
);
|
|
</script>
|
|
|
|
<div data-uix-canvas-inner>
|
|
<header>
|
|
<div data-uix-eyebrow>Media · Image</div>
|
|
<h1 data-uix-page-title>Image</h1>
|
|
<p data-uix-page-lede>
|
|
Responsive image surface with status-driven fallback. Four parts —
|
|
<code>Image</code> (provider), <code>Img</code>, <code>Fallback</code>,
|
|
<code>Error</code>. Reuses the existing <code>ImageProvider</code> from
|
|
<code>soma/layers</code> so the load lifecycle (idle / loading / loaded / error) drives the
|
|
recipe. Designed as a foundation other components reach for instead of dropping raw
|
|
<code><img></code> — Avatar.Image, Card hero, file thumbnails, etc. all benefit from
|
|
the shared loading / error contract. Aspect-ratio is composed via the existing
|
|
<a href="/uix/components/aspect-ratio"><AspectRatio></a> primitive.
|
|
</p>
|
|
<div data-uix-page-meta>
|
|
<span data-uix-meta-pill>
|
|
<span data-uix-meta-key>parts</span>{compiled.parts.order.length}
|
|
</span>
|
|
<span data-uix-meta-pill>
|
|
<span data-uix-meta-key>events</span>{events.length}
|
|
</span>
|
|
<span data-uix-meta-pill>
|
|
<span data-uix-meta-key>statuses</span>4
|
|
</span>
|
|
<span data-uix-meta-pill>
|
|
<span data-uix-meta-key>fit</span>5
|
|
</span>
|
|
<span data-uix-meta-pill>
|
|
<span data-uix-meta-key>sizes</span>5+intrinsic
|
|
</span>
|
|
<span data-uix-meta-pill>
|
|
<span data-uix-meta-key>scope</span>eidos
|
|
</span>
|
|
</div>
|
|
</header>
|
|
|
|
<!-- Live preview always rendered -->
|
|
<div data-uix-stage>
|
|
<div data-uix-stage-area bind:this={stageRef}>
|
|
<Image
|
|
src={effectiveSrc}
|
|
{alt}
|
|
{fit}
|
|
{position}
|
|
{radius}
|
|
size={size === '' ? undefined : size}
|
|
{placeholder}
|
|
{placeholderColor}
|
|
{delayMs}
|
|
{loading}
|
|
bind:imageStatus
|
|
/>
|
|
</div>
|
|
<div data-uix-stage-trace>
|
|
<span data-uix-stage-trace-key>trace</span>
|
|
<span>{trace.length === 0 ? 'no semantic events' : `${trace.length} event(s)`}</span>
|
|
<span style="color: var(--uix-text-faint)">·</span>
|
|
<span data-uix-stage-trace-key>status</span>
|
|
<span data-uix-status-chip data-status={imageStatus}>{imageStatus}</span>
|
|
<span style="margin-inline-start: auto;">
|
|
<span data-uix-stage-trace-key>fit</span> {fit} ·
|
|
<span data-uix-stage-trace-key>placeholder</span> {placeholder}
|
|
</span>
|
|
</div>
|
|
</div>
|
|
|
|
<div data-uix-tabs role="tablist">
|
|
<button data-uix-tab data-active={tab === 'live'} onclick={() => (tab = 'live')}>Live</button>
|
|
<button data-uix-tab data-active={tab === 'api'} onclick={() => (tab = 'api')}>
|
|
API <span data-uix-tab-count>19</span>
|
|
</button>
|
|
<button data-uix-tab data-active={tab === 'morfo'} onclick={() => (tab = 'morfo')}>
|
|
<span data-uix-layer-badge="morfo">morfo</span>
|
|
<span data-uix-tab-count>{partsList.length}p · {events.length}e</span>
|
|
</button>
|
|
<button data-uix-tab data-active={tab === 'sema'} onclick={() => (tab = 'sema')}>
|
|
<span data-uix-layer-badge="sema">sema</span>
|
|
<span data-uix-tab-count>{events.length}</span>
|
|
</button>
|
|
<button data-uix-tab data-active={tab === 'recipe'} onclick={() => (tab = 'recipe')}>Recipe</button
|
|
>
|
|
<button data-uix-tab data-active={tab === 'a11y'} onclick={() => (tab = 'a11y')}>A11y</button>
|
|
</div>
|
|
|
|
{#if tab === 'live'}
|
|
<section data-uix-section>
|
|
<h2 data-uix-section-title>Controls</h2>
|
|
<p data-uix-section-desc>
|
|
Image is eidos-native — no <span data-uix-layer-badge="soma">soma</span> split. The
|
|
Provider reads <code>ImageProvider</code> (soma/layers) to track the load lifecycle and
|
|
gate Fallback / Error slots conditionally.
|
|
</p>
|
|
|
|
<div data-uix-subsection-head>
|
|
<span data-uix-layer-badge="eidos">eidos</span> props · visual treatment
|
|
</div>
|
|
<div data-uix-controls>
|
|
<label data-uix-control>
|
|
<span data-uix-control-label>fit</span>
|
|
<span data-uix-chips role="radiogroup">
|
|
{#each ['cover', 'contain', 'fill', 'none', 'scale-down'] as f}
|
|
<button
|
|
data-uix-chip
|
|
data-active={fit === f}
|
|
onclick={() => (fit = f as ImageFit)}>{f}</button
|
|
>
|
|
{/each}
|
|
</span>
|
|
</label>
|
|
<label data-uix-control>
|
|
<span data-uix-control-label>position</span>
|
|
<span data-uix-chips role="radiogroup">
|
|
{#each ['center', 'top', 'bottom', 'start', 'end'] as p}
|
|
<button
|
|
data-uix-chip
|
|
data-active={position === p}
|
|
onclick={() => (position = p as ImagePosition)}>{p}</button
|
|
>
|
|
{/each}
|
|
</span>
|
|
</label>
|
|
<label data-uix-control>
|
|
<span data-uix-control-label>radius</span>
|
|
<span data-uix-chips role="radiogroup">
|
|
{#each ['none', 'sm', 'md', 'lg', 'full'] as r}
|
|
<button
|
|
data-uix-chip
|
|
data-active={radius === r}
|
|
onclick={() => (radius = r as ImageRadius)}>{r}</button
|
|
>
|
|
{/each}
|
|
</span>
|
|
</label>
|
|
<label data-uix-control>
|
|
<span data-uix-control-label>size</span>
|
|
<span data-uix-chips role="radiogroup">
|
|
<button data-uix-chip data-active={size === ''} onclick={() => (size = '')}
|
|
>intrinsic</button
|
|
>
|
|
{#each ['xs', 'sm', 'md', 'lg', 'xl'] as s}
|
|
<button
|
|
data-uix-chip
|
|
data-active={size === s}
|
|
onclick={() => (size = s as ImageSize)}>{s}</button
|
|
>
|
|
{/each}
|
|
</span>
|
|
</label>
|
|
</div>
|
|
|
|
<div data-uix-subsection-head>Placeholder + lifecycle</div>
|
|
<div data-uix-controls>
|
|
<label data-uix-control>
|
|
<span data-uix-control-label>placeholder</span>
|
|
<span data-uix-chips role="radiogroup">
|
|
{#each ['skeleton', 'color', 'none'] as p}
|
|
<button
|
|
data-uix-chip
|
|
data-active={placeholder === p}
|
|
onclick={() => (placeholder = p as ImagePlaceholder)}>{p}</button
|
|
>
|
|
{/each}
|
|
</span>
|
|
</label>
|
|
<label data-uix-control>
|
|
<span data-uix-control-label>placeholderColor</span>
|
|
<span data-uix-chips role="radiogroup">
|
|
{#each ['primary', 'secondary', 'neutral', 'affirm', 'fulfill', 'risk', 'threat', 'loss'] as c}
|
|
<button
|
|
data-uix-chip
|
|
data-active={placeholderColor === c}
|
|
onclick={() => (placeholderColor = c)}
|
|
disabled={placeholder !== 'color'}>{c}</button
|
|
>
|
|
{/each}
|
|
</span>
|
|
</label>
|
|
<label data-uix-control>
|
|
<span data-uix-control-label
|
|
>delayMs <span data-uix-control-hint>fallback delay</span></span
|
|
>
|
|
<input
|
|
type="number"
|
|
bind:value={delayMs}
|
|
min="0"
|
|
max="3000"
|
|
step="100"
|
|
style="inline-size: 6rem;"
|
|
/>
|
|
</label>
|
|
<label data-uix-control>
|
|
<span data-uix-control-label>loading</span>
|
|
<span data-uix-chips role="radiogroup">
|
|
{#each ['lazy', 'eager'] as l}
|
|
<button
|
|
data-uix-chip
|
|
data-active={loading === l}
|
|
onclick={() => (loading = l as 'lazy' | 'eager')}>{l}</button
|
|
>
|
|
{/each}
|
|
</span>
|
|
</label>
|
|
</div>
|
|
|
|
<div data-uix-subsection-head>Demo content</div>
|
|
<div data-uix-controls>
|
|
<label data-uix-control>
|
|
<span data-uix-control-label>src</span>
|
|
<input type="text" bind:value={src} disabled={breakImage} />
|
|
</label>
|
|
<label data-uix-control>
|
|
<span data-uix-control-label>alt</span>
|
|
<input type="text" bind:value={alt} />
|
|
</label>
|
|
<label data-uix-control>
|
|
<span data-uix-control-label
|
|
>break image <span data-uix-control-hint>force error state</span></span
|
|
>
|
|
<span data-uix-switch>
|
|
<input type="checkbox" bind:checked={breakImage} />
|
|
<span data-uix-switch-label>{breakImage ? 'on' : 'off'}</span>
|
|
</span>
|
|
</label>
|
|
<label data-uix-control>
|
|
<span data-uix-control-label>reload</span>
|
|
<button data-uix-chip onclick={reload}>↻ re-fetch</button>
|
|
</label>
|
|
</div>
|
|
|
|
<div data-uix-code style="margin-top: var(--uix-space-4);">
|
|
<div data-uix-code-head>
|
|
<span data-uix-layer-badge="eidos">eidos</span>
|
|
<span>composition · all props applied</span>
|
|
<span data-uix-code-lang>svelte</span>
|
|
</div>
|
|
<pre><code>{eidosSnippet}</code></pre>
|
|
</div>
|
|
|
|
<!-- ── Patterns · common shapes ──────────────────────────────────── -->
|
|
<div data-uix-subsection-head>Patterns · common shapes</div>
|
|
<div data-uix-pattern-stack>
|
|
<!-- Aspect ratios -->
|
|
<div data-uix-pattern>
|
|
<h3 data-uix-pattern-title>
|
|
Compose with <code><AspectRatio></code> for fixed ratios
|
|
</h3>
|
|
<div data-uix-pattern-row>
|
|
<div data-uix-stage-mini>
|
|
<code>1 / 1 — square</code>
|
|
<AspectRatio ratio={1} style="inline-size: 8rem;">
|
|
<Image
|
|
src="https://picsum.photos/seed/uix-sq/400/400"
|
|
alt="Square"
|
|
fit="cover"
|
|
radius="md"
|
|
/>
|
|
</AspectRatio>
|
|
</div>
|
|
<div data-uix-stage-mini>
|
|
<code>16 / 9 — widescreen</code>
|
|
<AspectRatio ratio="16/9" style="inline-size: 14rem;">
|
|
<Image
|
|
src="https://picsum.photos/seed/uix-wide/640/360"
|
|
alt="Widescreen"
|
|
fit="cover"
|
|
radius="md"
|
|
/>
|
|
</AspectRatio>
|
|
</div>
|
|
<div data-uix-stage-mini>
|
|
<code>4 / 3 — standard</code>
|
|
<AspectRatio ratio="4/3" style="inline-size: 12rem;">
|
|
<Image
|
|
src="https://picsum.photos/seed/uix-43/480/360"
|
|
alt="4:3"
|
|
fit="cover"
|
|
radius="md"
|
|
/>
|
|
</AspectRatio>
|
|
</div>
|
|
<div data-uix-stage-mini>
|
|
<code>21 / 9 — ultrawide</code>
|
|
<AspectRatio ratio="21/9" style="inline-size: 18rem;">
|
|
<Image
|
|
src="https://picsum.photos/seed/uix-uw/840/360"
|
|
alt="Ultrawide"
|
|
fit="cover"
|
|
radius="md"
|
|
/>
|
|
</AspectRatio>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- Size presets -->
|
|
<div data-uix-pattern>
|
|
<h3 data-uix-pattern-title>Size presets — square thumbnails</h3>
|
|
<div data-uix-pattern-row>
|
|
{#each ['xs', 'sm', 'md', 'lg', 'xl'] as s (s)}
|
|
<div data-uix-stage-mini>
|
|
<code>size={s}</code>
|
|
<Image
|
|
src={`https://picsum.photos/seed/uix-${s}/400/400`}
|
|
alt={`${s} thumbnail`}
|
|
size={s as ImageSize}
|
|
radius="md"
|
|
/>
|
|
</div>
|
|
{/each}
|
|
</div>
|
|
</div>
|
|
|
|
<!-- Object-fit -->
|
|
<div data-uix-pattern>
|
|
<h3 data-uix-pattern-title>
|
|
Object-fit — same box, different scaling
|
|
</h3>
|
|
<div data-uix-pattern-row>
|
|
{#each ['cover', 'contain', 'fill', 'none', 'scale-down'] as f (f)}
|
|
<div data-uix-stage-mini>
|
|
<code>fit={f}</code>
|
|
<AspectRatio ratio="1/1" style="inline-size: 7rem;">
|
|
<Image
|
|
src="https://picsum.photos/seed/uix-fit/600/300"
|
|
alt={`fit ${f}`}
|
|
fit={f as ImageFit}
|
|
radius="md"
|
|
placeholder="color"
|
|
placeholderColor="neutral"
|
|
/>
|
|
</AspectRatio>
|
|
</div>
|
|
{/each}
|
|
</div>
|
|
</div>
|
|
|
|
<!-- Placeholder modes -->
|
|
<div data-uix-pattern>
|
|
<h3 data-uix-pattern-title>
|
|
Placeholder modes — visible during load with <code>delayMs=1500</code>
|
|
</h3>
|
|
<div data-uix-pattern-row>
|
|
<div data-uix-stage-mini>
|
|
<code>skeleton</code>
|
|
<Image
|
|
src="https://picsum.photos/seed/uix-skel/400/300"
|
|
alt="Skeleton placeholder"
|
|
size="md"
|
|
radius="md"
|
|
placeholder="skeleton"
|
|
delayMs={1500}
|
|
/>
|
|
</div>
|
|
<div data-uix-stage-mini>
|
|
<code>color (affirm)</code>
|
|
<Image
|
|
src="https://picsum.photos/seed/uix-col-a/400/300"
|
|
alt="Color placeholder"
|
|
size="md"
|
|
radius="md"
|
|
placeholder="color"
|
|
placeholderColor="affirm"
|
|
delayMs={1500}
|
|
/>
|
|
</div>
|
|
<div data-uix-stage-mini>
|
|
<code>color (#7c3aed)</code>
|
|
<Image
|
|
src="https://picsum.photos/seed/uix-col-c/400/300"
|
|
alt="Custom color placeholder"
|
|
size="md"
|
|
radius="md"
|
|
placeholder="color"
|
|
placeholderColor="#7c3aed"
|
|
delayMs={1500}
|
|
/>
|
|
</div>
|
|
<div data-uix-stage-mini>
|
|
<code>none</code>
|
|
<Image
|
|
src="https://picsum.photos/seed/uix-none/400/300"
|
|
alt="No placeholder"
|
|
size="md"
|
|
radius="md"
|
|
placeholder="none"
|
|
delayMs={1500}
|
|
/>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- Error state -->
|
|
<div data-uix-pattern>
|
|
<h3 data-uix-pattern-title>
|
|
Error state — broken URL falls back to <code><Image.Error></code>
|
|
</h3>
|
|
<div data-uix-pattern-row>
|
|
<div data-uix-stage-mini>
|
|
<code>shorthand error string</code>
|
|
<Image
|
|
src="https://broken.invalid/a.png"
|
|
alt="Broken"
|
|
size="md"
|
|
radius="md"
|
|
errorFallback="✕ failed"
|
|
/>
|
|
</div>
|
|
<div data-uix-stage-mini>
|
|
<code>fallbackSrc → swap URL</code>
|
|
<Image
|
|
src="https://broken.invalid/b.png"
|
|
alt="With fallbackSrc"
|
|
size="md"
|
|
radius="md"
|
|
fallbackSrc="https://picsum.photos/seed/uix-fb/400/400"
|
|
/>
|
|
</div>
|
|
<div data-uix-stage-mini>
|
|
<code>composed Image.Error</code>
|
|
<Image src="https://broken.invalid/c.png" alt="Composed error" size="md" radius="md">
|
|
<Image.Img />
|
|
<Image.Fallback />
|
|
<Image.Error>
|
|
<span style="font-size: var(--uix-font-size-lg); font-weight: 600;">⚠</span>
|
|
</Image.Error>
|
|
</Image>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<!-- Radius scale -->
|
|
<div data-uix-pattern>
|
|
<h3 data-uix-pattern-title>Radius scale</h3>
|
|
<div data-uix-pattern-row>
|
|
{#each ['none', 'sm', 'md', 'lg', 'full'] as r (r)}
|
|
<div data-uix-stage-mini>
|
|
<code>radius={r}</code>
|
|
<Image
|
|
src={`https://picsum.photos/seed/uix-r-${r}/400/400`}
|
|
alt={`radius ${r}`}
|
|
size="md"
|
|
radius={r as ImageRadius}
|
|
/>
|
|
</div>
|
|
{/each}
|
|
</div>
|
|
</div>
|
|
</div>
|
|
</section>
|
|
{/if}
|
|
|
|
{#if tab === 'api'}
|
|
<section data-uix-section>
|
|
<h2 data-uix-section-title>API reference</h2>
|
|
<p data-uix-section-desc>
|
|
`<code><Image></code>` exposes the native `<code><img></code>` attribute
|
|
surface (src / srcset / sizes / loading / decoding / fetchpriority / crossorigin /
|
|
referrerpolicy / width / height) plus the visual chrome props below.
|
|
</p>
|
|
|
|
<div data-uix-subsection-head>Image (provider)</div>
|
|
<div data-uix-table-wrap>
|
|
<table data-uix-table>
|
|
<thead><tr><th>Prop</th><th>Type</th><th>Default</th><th>Description</th></tr></thead>
|
|
<tbody>
|
|
<tr>
|
|
<td class="name">src</td>
|
|
<td class="type">string | null</td>
|
|
<td class="default empty">—</td>
|
|
<td>Primary image URL. Null forces the Fallback slot.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">alt</td>
|
|
<td class="type">string</td>
|
|
<td class="default">''</td>
|
|
<td>Accessible name. Required for meaningful images.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">srcset / sizes</td>
|
|
<td class="type">string</td>
|
|
<td class="default empty">—</td>
|
|
<td>Responsive source set forwarded to the inner <code><img></code>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">loading</td>
|
|
<td class="type">'lazy' | 'eager'</td>
|
|
<td class="default">'lazy'</td>
|
|
<td>Native lazy-load hint.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">decoding</td>
|
|
<td class="type">'sync' | 'async' | 'auto'</td>
|
|
<td class="default">'async'</td>
|
|
<td>Native decode hint.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">fetchpriority</td>
|
|
<td class="type">'high' | 'low' | 'auto'</td>
|
|
<td class="default">'auto'</td>
|
|
<td>Native fetch-priority hint (use <code>high</code> for above-the-fold heroes).</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">crossorigin / referrerpolicy</td>
|
|
<td class="type">native attrs</td>
|
|
<td class="default empty">—</td>
|
|
<td>Forwarded verbatim.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">width / height</td>
|
|
<td class="type">number | string</td>
|
|
<td class="default empty">—</td>
|
|
<td>
|
|
Intrinsic dims forwarded to <code><img></code>. Prevents layout shift
|
|
when known.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">fit</td>
|
|
<td class="type">'cover' | 'contain' | 'fill' | 'none' | 'scale-down'</td>
|
|
<td class="default">'cover'</td>
|
|
<td>Object-fit on the inner <code><img></code>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">position</td>
|
|
<td class="type">'center' | 'top' | 'bottom' | 'start' | 'end'</td>
|
|
<td class="default">'center'</td>
|
|
<td>
|
|
Object-position keyword. RTL-aware (<code>start</code>/<code>end</code>
|
|
flip).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">radius</td>
|
|
<td class="type">'none' | 'sm' | 'md' | 'lg' | 'full'</td>
|
|
<td class="default">'none'</td>
|
|
<td>Corner radius.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">size</td>
|
|
<td class="type">'xs' | 'sm' | 'md' | 'lg' | 'xl'</td>
|
|
<td class="default empty">— intrinsic</td>
|
|
<td>
|
|
Preset square box (64 / 96 / 160 / 240 / 360 px). Omit to take intrinsic dims
|
|
or compose with <code><AspectRatio></code>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">placeholder</td>
|
|
<td class="type">'skeleton' | 'color' | 'none'</td>
|
|
<td class="default">'skeleton'</td>
|
|
<td>
|
|
Visual during load. <code>skeleton</code> shimmers,
|
|
<code>color</code> paints a flat tint, <code>none</code> stays transparent.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">placeholderColor</td>
|
|
<td class="type">ColorRole | string</td>
|
|
<td class="default">'neutral'</td>
|
|
<td>
|
|
Tint when <code>placeholder="color"</code>. Canonical role or any CSS color
|
|
string (same union as Card / Avatar).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">delayMs</td>
|
|
<td class="type">number</td>
|
|
<td class="default">0</td>
|
|
<td>
|
|
Delay before showing the Fallback while loading. Error and no-src fallbacks
|
|
render immediately.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">imageStatus</td>
|
|
<td class="type">'idle' | 'loading' | 'loaded' | 'error'</td>
|
|
<td class="default">'idle'</td>
|
|
<td>
|
|
Bindable status. Set to <code>'loaded'</code> for known-safe local assets to
|
|
skip the loading flicker.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">fallback</td>
|
|
<td class="type">string | Snippet</td>
|
|
<td class="default empty">—</td>
|
|
<td>
|
|
Shortcut: string → render as a placeholder <code><img></code>; snippet →
|
|
render as content. Skip if you compose <code><Image.Fallback></code>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">errorFallback</td>
|
|
<td class="type">string | Snippet</td>
|
|
<td class="default empty">—</td>
|
|
<td>
|
|
Same shape as <code>fallback</code> but for the error state. Skip if you
|
|
compose <code><Image.Error></code>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">fallbackSrc</td>
|
|
<td class="type">string</td>
|
|
<td class="default empty">—</td>
|
|
<td>
|
|
Shortcut: swap the inner <code><img src></code> on error instead of
|
|
replacing the markup.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">onload, onerror, onImageStatusChange</td>
|
|
<td class="type">callbacks</td>
|
|
<td class="default empty">—</td>
|
|
<td>Native events + status-change callback.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
|
|
<div data-uix-subsection-head>Sub-components</div>
|
|
<div data-uix-table-wrap>
|
|
<table data-uix-table>
|
|
<thead><tr><th>Part</th><th>Element</th><th>Visible when</th></tr></thead>
|
|
<tbody>
|
|
<tr>
|
|
<td class="name">Image.Img</td>
|
|
<td class="type"><img></td>
|
|
<td>
|
|
Status ≠ error AND src is present. Use when composing children manually;
|
|
the shorthand Provider renders this for you.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">Image.Fallback</td>
|
|
<td class="type"><span></td>
|
|
<td>
|
|
Status is idle / loading AND delay has elapsed. Hidden once the image loads
|
|
or errors.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">Image.Error</td>
|
|
<td class="type"><span> (role="img")</td>
|
|
<td>
|
|
Status is error. Carries a translated <code>aria-label</code> so screen
|
|
readers announce the broken image, not arbitrary chrome.
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
|
|
<div data-uix-subsection-head>Reference comparison</div>
|
|
<div data-uix-table-wrap>
|
|
<table data-uix-table>
|
|
<thead><tr><th>Library</th><th>Closest equivalent</th><th>Difference</th></tr></thead>
|
|
<tbody>
|
|
<tr>
|
|
<td class="name">chakra-ui</td>
|
|
<td><code><Image src fallback fallbackSrc onError onLoad></code></td>
|
|
<td>
|
|
Chakra exposes <code>fallback</code> + <code>fallbackSrc</code> + status
|
|
callbacks. UIX matches that shape and adds the structured <code>Image.Fallback</code>
|
|
/ <code>Image.Error</code> slots, the <code>placeholder</code> mode and the
|
|
<code>color-mix()</code> custom placeholder color.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">mantine</td>
|
|
<td><code><Image radius fit loading placeholder></code></td>
|
|
<td>
|
|
Mantine has <code>fit</code> + <code>radius</code> + a custom placeholder
|
|
slot. UIX adds canonical <code>data-status</code> states tied to the
|
|
recipe, so other components (Card, Carousel) inherit the same loading look.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">radix-themes</td>
|
|
<td>—</td>
|
|
<td>Radix doesn't ship a public Image — only Avatar.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">shadcn/ui</td>
|
|
<td>—</td>
|
|
<td>shadcn uses plain Next.js <code><Image></code> directly.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">bits-ui / ark-ui</td>
|
|
<td>—</td>
|
|
<td>
|
|
Neither headless lib ships a public Image. They cover the status machinery
|
|
as an internal helper for Avatar. UIX promotes that helper
|
|
(<code>ImageProvider</code> in soma/layers) into a public component.
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</section>
|
|
{/if}
|
|
|
|
{#if tab === 'morfo'}
|
|
<section data-uix-section>
|
|
<h2 data-uix-section-title>
|
|
<span data-uix-layer-badge="morfo">morfo</span>
|
|
· declarative contract
|
|
</h2>
|
|
<p data-uix-section-desc>
|
|
Eidos-scoped morfo. Source: <code>src/uix/morfo/components/image.ts</code>.
|
|
</p>
|
|
|
|
<div data-uix-table-wrap>
|
|
<table data-uix-table>
|
|
<thead><tr><th>Field</th><th>Value</th></tr></thead>
|
|
<tbody>
|
|
<tr><td class="name">name</td><td>{imageMorfo.name}</td></tr>
|
|
<tr><td class="name">kebab</td><td><code>{imageMorfo.kebab}</code></td></tr>
|
|
<tr><td class="name">scope</td><td>{imageMorfo.scope.join(', ')}</td></tr>
|
|
<tr><td class="name">parts</td><td>{partsList.length}</td></tr>
|
|
<tr><td class="name">events</td><td>{events.length}</td></tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
|
|
<div data-uix-subsection-head>Parts</div>
|
|
<div data-uix-table-wrap>
|
|
<table data-uix-table>
|
|
<thead>
|
|
<tr>
|
|
<th>kebab</th>
|
|
<th>marker</th>
|
|
<th>element</th>
|
|
<th>archetype</th>
|
|
<th>role</th>
|
|
<th>optional</th>
|
|
</tr>
|
|
</thead>
|
|
<tbody>
|
|
{#each partsList as part (part.kebab)}
|
|
<tr>
|
|
<td class="name">{part.kebab}</td>
|
|
<td><code data-uix-part-marker>[{part.marker}]</code></td>
|
|
<td class="type"><{part.defaultElement}></td>
|
|
<td class="type">{part.archetype ?? '—'}</td>
|
|
<td class="type">{part.role ?? '—'}</td>
|
|
<td class="default">{part.optional ? 'yes' : 'no'}</td>
|
|
</tr>
|
|
{/each}
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
|
|
<div data-uix-subsection-head>Provider · data-status states</div>
|
|
<div data-uix-table-wrap>
|
|
<table data-uix-table>
|
|
<thead><tr><th>State</th><th>Trigger</th><th>Slot visible</th></tr></thead>
|
|
<tbody>
|
|
<tr>
|
|
<td class="name"><code>idle</code></td>
|
|
<td>No src set, image just mounted</td>
|
|
<td>Fallback</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name"><code>loading</code></td>
|
|
<td>Src present, request in flight</td>
|
|
<td>Fallback (after delayMs)</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name"><code>loaded</code></td>
|
|
<td>Native <code>onload</code> fired</td>
|
|
<td>Img (fades in)</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name"><code>error</code></td>
|
|
<td>Native <code>onerror</code> fired</td>
|
|
<td>Error</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</section>
|
|
{/if}
|
|
|
|
{#if tab === 'sema'}
|
|
<section data-uix-section>
|
|
<h2 data-uix-section-title>
|
|
<span data-uix-layer-badge="sema">sema</span> · events
|
|
</h2>
|
|
<p data-uix-section-desc>
|
|
Image declares <strong>no semantic events</strong>. The load lifecycle is a passive
|
|
observation, not an evaluative act. Consumers wanting a perceptual signal when an
|
|
image lands wire it to the surrounding context — a gallery's
|
|
<code>commit-select</code> on click, a hero's <code>emerge-mount</code> on the
|
|
parent dialog, etc.
|
|
</p>
|
|
<p data-uix-section-desc>
|
|
If you need to react programmatically, bind <code>imageStatus</code> or attach
|
|
<code>onImageStatusChange</code> / <code>onload</code> / <code>onerror</code>.
|
|
</p>
|
|
</section>
|
|
{/if}
|
|
|
|
{#if tab === 'recipe'}
|
|
<section data-uix-section>
|
|
<h2 data-uix-section-title>Eidos recipe</h2>
|
|
<p data-uix-section-desc>
|
|
Recipe lives in <code>src/uix/eidos/components/image/image.css</code>. Layering is
|
|
status-driven: the inner <code><img></code> sits on top with
|
|
<code>opacity</code> tied to <code>data-status</code>, the Fallback covers the box
|
|
behind it, the Error slot replaces both when the load fails.
|
|
</p>
|
|
<div data-uix-table-wrap>
|
|
<table data-uix-table>
|
|
<thead><tr><th>Selector</th><th>Owner</th><th>Purpose</th></tr></thead>
|
|
<tbody>
|
|
<tr>
|
|
<td class="name"><code>[data-image]</code></td>
|
|
<td><span data-uix-tag data-kind="morfo">morfo</span></td>
|
|
<td>Provider marker. <code>position: relative</code> + overflow clip + radius.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name"><code>[data-image][data-size='xs'..'xl']</code></td>
|
|
<td><span data-uix-tag data-kind="eidos">eidos</span></td>
|
|
<td>Preset square boxes (64 / 96 / 160 / 240 / 360 px).</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name"><code>[data-image][data-radius='none'..'full']</code></td>
|
|
<td><span data-uix-tag data-kind="eidos">eidos</span></td>
|
|
<td>Sets <code>--_image-radius</code>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name"><code>[data-image-img]</code></td>
|
|
<td><span data-uix-tag data-kind="morfo">morfo</span></td>
|
|
<td>Inner <code><img></code>. Default <code>object-fit: cover</code> + fade-in transition.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name"><code>[data-image][data-fit='cover'..'scale-down']</code></td>
|
|
<td><span data-uix-tag data-kind="eidos">eidos</span></td>
|
|
<td>Overrides <code>object-fit</code> on the inner <code><img></code>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name"><code>[data-image][data-position='center'..'end']</code></td>
|
|
<td><span data-uix-tag data-kind="eidos">eidos</span></td>
|
|
<td><code>object-position</code> keyword (RTL-aware).</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name"><code>[data-image-fallback]</code></td>
|
|
<td><span data-uix-tag data-kind="morfo">morfo</span></td>
|
|
<td>Absolutely-positioned slot behind the <code><img></code>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name"><code>[data-placeholder='skeleton'] [data-image-fallback]::before</code></td>
|
|
<td><span data-uix-tag data-kind="eidos">eidos</span></td>
|
|
<td>
|
|
Shimmering gradient via the <code>image-shimmer</code> keyframes. Disabled
|
|
under <code>prefers-reduced-motion</code>.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name"><code>[data-placeholder='color']</code></td>
|
|
<td><span data-uix-tag data-kind="eidos">eidos</span></td>
|
|
<td>Flat tint from the 8-color palette OR a custom CSS color via <code>color-mix()</code>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name"><code>[data-image-error]</code></td>
|
|
<td><span data-uix-tag data-kind="morfo">morfo</span></td>
|
|
<td>Error slot. Shown when status is <code>error</code>.</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name"><code>@media (prefers-reduced-motion: reduce)</code></td>
|
|
<td><span data-uix-tag data-kind="eidos">eidos</span></td>
|
|
<td>Disables the fade transition and shimmer animation.</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</section>
|
|
{/if}
|
|
|
|
{#if tab === 'a11y'}
|
|
<section data-uix-section>
|
|
<h2 data-uix-section-title>Accessibility</h2>
|
|
<div data-uix-table-wrap>
|
|
<table data-uix-table>
|
|
<thead><tr><th>Concern</th><th>Contract</th></tr></thead>
|
|
<tbody>
|
|
<tr>
|
|
<td class="name">Alt text</td>
|
|
<td>
|
|
Required for meaningful images — forward via <code>alt</code> on
|
|
<code><Image></code>. Decorative? Use <code>alt=""</code> (the
|
|
surrounding context carries the meaning).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">Loading region</td>
|
|
<td>
|
|
The Fallback slot gets a translated <code>aria-label="Loading image"</code>
|
|
(<code>es: 'Cargando imagen'</code>). Override on
|
|
<code><Image.Fallback aria-label></code> when context demands it (e.g.
|
|
"Loading product photo").
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">Error state</td>
|
|
<td>
|
|
The Error slot is <code>role="img"</code> + translated
|
|
<code>aria-label="Image failed to load"</code> so screen readers know it's
|
|
a broken image, not arbitrary chrome.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">Decorative vs meaningful</td>
|
|
<td>
|
|
Decorative images get <code>alt=""</code> — they're skipped by screen
|
|
readers. Meaningful ones describe what they show (avoid "image of …" —
|
|
the role already tells the user it's an image).
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">Loading strategy</td>
|
|
<td>
|
|
Default <code>loading="lazy"</code> for below-the-fold thumbnails. Switch to
|
|
<code>loading="eager"</code> + <code>fetchpriority="high"</code> for
|
|
above-the-fold heroes that drive the LCP metric.
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<td class="name">Reduced motion</td>
|
|
<td>
|
|
<code>prefers-reduced-motion: reduce</code> disables both the fade-in
|
|
transition and the skeleton shimmer. The Image still renders; only the
|
|
animations stop.
|
|
</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
</div>
|
|
</section>
|
|
{/if}
|
|
</div>
|
|
|
|
<style>
|
|
[data-uix-pattern-stack] {
|
|
display: flex;
|
|
flex-direction: column;
|
|
gap: var(--uix-space-5);
|
|
}
|
|
[data-uix-pattern] {
|
|
display: block;
|
|
}
|
|
[data-uix-pattern-row] {
|
|
display: flex;
|
|
flex-wrap: wrap;
|
|
align-items: flex-start;
|
|
gap: var(--uix-space-4);
|
|
padding: var(--uix-space-4);
|
|
border: 1px solid var(--uix-border);
|
|
border-radius: var(--uix-radius-md);
|
|
}
|
|
[data-uix-stage-mini] {
|
|
display: flex;
|
|
flex-direction: column;
|
|
gap: var(--uix-space-2);
|
|
align-items: flex-start;
|
|
min-inline-size: 7rem;
|
|
}
|
|
[data-uix-stage-mini] > code {
|
|
font-size: var(--uix-font-size-xs);
|
|
color: var(--uix-text-faint);
|
|
}
|
|
[data-uix-status-chip] {
|
|
font-family: var(--uix-font-mono);
|
|
font-size: var(--uix-font-size-xs);
|
|
padding: 0 var(--uix-space-1);
|
|
border-radius: var(--uix-radius-sm);
|
|
background: var(--uix-bg-subtle, var(--color-surface-raised));
|
|
}
|
|
[data-uix-status-chip][data-status='loaded'] {
|
|
color: var(--color-affirm-text);
|
|
background: var(--color-affirm-track);
|
|
}
|
|
[data-uix-status-chip][data-status='error'] {
|
|
color: var(--color-threat-text);
|
|
background: var(--color-threat-track);
|
|
}
|
|
[data-uix-status-chip][data-status='loading'] {
|
|
color: var(--color-risk-text);
|
|
background: var(--color-risk-track);
|
|
}
|
|
h3[data-uix-pattern-title] {
|
|
margin: 0 0 var(--uix-space-3);
|
|
font-family: var(--uix-font-ui);
|
|
font-size: var(--uix-font-size-sm);
|
|
font-weight: 600;
|
|
color: var(--uix-text-faint);
|
|
text-transform: uppercase;
|
|
letter-spacing: 0.04em;
|
|
}
|
|
</style>
|