@xtyle/astro 0.5.0

package/src/Dock.astro

@@ -0,0 +1,79 @@
+---
+import { renderFragmentLight, composeFallbackSlot } from "@xtyle/core/elements/ssr";
+
+import type { FullTone as Tone } from "@xtyle/core";
+type DockSide = "left" | "right";
+type Size = "sm" | "md" | "lg";
+
+interface Props {
+	side?: DockSide;
+	size?: Size;
+	tone?: Tone;
+	reverseEdge?: boolean;
+	edgeWidth?: "thin" | "thick" | "bold";
+	nav?: boolean;
+	label?: string;
+	"aria-label"?: string;
+	/** Drop the visible `label` header while keeping `label` as the dock's accessible name. */
+	hideHeader?: boolean;
+	/** Render zero-JS: emit the declarative shadow but never load the runtime to hydrate it. */
+	static?: boolean;
+	class?: string;
+	/** Any other attribute (`id`, `title`, `data-*`, `aria-*`, …) passes through to the element. */
+	[key: string]: unknown;
+}
+
+const {
+	side = "left",
+	size = "md",
+	tone,
+	reverseEdge = false,
+	edgeWidth,
+	nav = false,
+	label,
+	"aria-label": ariaLabel,
+	hideHeader = false,
+	static: isStatic = false,
+	class: extra,
+	...rest
+} = Astro.props;
+
+const hasHeader = Astro.slots.has("header");
+const hasFooter = Astro.slots.has("footer");
+
+const bindings = {
+	side,
+	size,
+	tone: tone ?? null,
+	reverseEdge,
+	edgeWidth: edgeWidth ?? null,
+	nav,
+	label: label ?? null,
+	hasAriaLabel: !!ariaLabel,
+	hideHeader,
+};
+const light = await renderFragmentLight("dock", bindings);
+const headerHtml = hasHeader ? await Astro.slots.render("header") : null;
+const bodyHtml = Astro.slots.has("default") ? await Astro.slots.render("default") : "";
+const footerHtml = hasFooter ? await Astro.slots.render("footer") : "";
+const composed = composeFallbackSlot(light, "header", headerHtml)
+	.replace("<slot></slot>", () => bodyHtml)
+	.replace('<slot name="footer"></slot>', () => footerHtml);
+---
+
+<xtyle-dock
+	side={side}
+	size={size}
+	tone={tone}
+	reverse-edge={reverseEdge || undefined}
+	edge-width={edgeWidth}
+	nav={nav || undefined}
+	label={label}
+	aria-label={ariaLabel}
+	hide-header={hideHeader || undefined}
+	class={extra}
+	set:html={composed}
+	{...rest}
+/>
+
+{!isStatic && <script>import "@xtyle/core/elements";</script>}

package/src/DockZone.astro

@@ -0,0 +1,17 @@
+---
+interface Props {
+	class?: string;
+	/** Any other attribute (`style`, `id`, `data-*`, `aria-*`, …) passes through to the element. Set a `height` so the workspace has a definite size to fill. */
+	[key: string]: unknown;
+}
+
+const { class: extra, ...rest } = Astro.props;
+---
+
+<xtyle-dock-zone class:list={[extra]} {...rest}>
+	<slot />
+</xtyle-dock-zone>
+
+<script>
+	import "@xtyle/core/elements";
+</script>

package/src/Eyebrow.astro

@@ -0,0 +1,30 @@
+---
+import { renderFragmentLight } from "@xtyle/core/elements/ssr";
+
+type EyebrowTag = "p" | "span" | "div";
+type EyebrowTone = "accent" | "muted" | "subtle";
+type EyebrowTracking = "normal" | "wide";
+
+interface Props {
+	as?: EyebrowTag;
+	tone?: EyebrowTone;
+	tracking?: EyebrowTracking;
+	/** Render zero-JS: emit the resolved light-DOM markup but never load the runtime to hydrate it. */
+	static?: boolean;
+	class?: string;
+	/** Any other attribute (`id`, `title`, `data-*`, `aria-*`, …) passes through to the element. */
+	[key: string]: unknown;
+}
+
+const { as = "p", tone = "accent", tracking = "normal", static: isStatic = false, class: extra, ...rest } =
+	Astro.props;
+
+const bindings = { as, tone, tracking };
+const chrome = await renderFragmentLight("eyebrow", bindings);
+const slotHtml = Astro.slots.has("default") ? await Astro.slots.render("default") : "";
+const composed = chrome.replace("<slot></slot>", () => slotHtml);
+---
+
+<xtyle-eyebrow as={as} tone={tone} tracking={tracking} class={extra} set:html={composed} {...rest} />
+
+{!isStatic && <script>import "@xtyle/core/elements";</script>}

package/src/Field.astro

@@ -0,0 +1,117 @@
+---
+import { renderFragmentLight, composeFallbackSlot } from "@xtyle/core/elements/ssr";
+
+type Size = "sm" | "md" | "lg";
+
+interface Props {
+	label?: string;
+	name?: string;
+	type?: string;
+	placeholder?: string;
+	value?: string;
+	size?: Size;
+	disabled?: boolean;
+	readonly?: boolean;
+	invalid?: boolean;
+	required?: boolean;
+	clearable?: boolean;
+	description?: string;
+	error?: string;
+	"aria-label"?: string;
+	/** Type-ahead suggestions: `string[]` or `{ value, label }[]`, rendered into the field's `<datalist>`
+	 * once the element upgrades. Needs the runtime (not `static`), since the datalist is wired on the client. */
+	options?: ReadonlyArray<string | { value: string; label?: string }>;
+	/** Render the input in the monospace stack for code-shaped values. */
+	mono?: boolean;
+	/** Render zero-JS: emit the declarative shadow but never load the runtime to hydrate it. */
+	static?: boolean;
+	class?: string;
+	/** Any other attribute (`id`, `title`, `data-*`, `aria-*`, …) passes through to the element. */
+	[key: string]: unknown;
+}
+
+const {
+	label,
+	name,
+	type = "text",
+	placeholder,
+	value,
+	size = "md",
+	disabled = false,
+	readonly = false,
+	invalid = false,
+	required = false,
+	clearable = false,
+	description,
+	error,
+	"aria-label": ariaLabel,
+	options,
+	mono = false,
+	static: isStatic = false,
+	class: extra,
+	...rest
+} = Astro.props;
+
+const uid = Math.random().toString(36).slice(2, 8);
+const inputId = `xtyle-field-${uid}`;
+const descriptionId = `xtyle-field-desc-${uid}`;
+const errorId = `xtyle-field-error-${uid}`;
+
+const hasPrefix = Astro.slots.has("prefix");
+const hasSuffix = Astro.slots.has("suffix");
+const hasRevealIcon = Astro.slots.has("reveal-icon");
+const hasClearIcon = Astro.slots.has("clear-icon");
+
+const bindings = {
+	label: label ?? null,
+	name: name ?? null,
+	type,
+	placeholder: placeholder ?? null,
+	value: value ?? null,
+	size,
+	disabled,
+	readonly,
+	invalid,
+	required,
+	clearable,
+	mono,
+	description: description ?? null,
+	error: error ?? null,
+	ariaLabel: ariaLabel ?? null,
+	inputId,
+	descriptionId,
+	errorId,
+};
+const light = await renderFragmentLight("field", bindings);
+const prefixHtml = hasPrefix ? await Astro.slots.render("prefix") : "";
+const suffixHtml = hasSuffix ? await Astro.slots.render("suffix") : "";
+const revealHtml = hasRevealIcon ? await Astro.slots.render("reveal-icon") : null;
+const clearHtml = hasClearIcon ? await Astro.slots.render("clear-icon") : null;
+const composed = composeFallbackSlot(composeFallbackSlot(light, "reveal-icon", revealHtml), "clear-icon", clearHtml)
+	.replace('<slot name="prefix"></slot>', () => prefixHtml)
+	.replace('<slot name="suffix"></slot>', () => suffixHtml);
+---
+
+<xtyle-field
+	label={label}
+	name={name}
+	type={type}
+	placeholder={placeholder}
+	value={value}
+	size={size}
+	disabled={disabled || undefined}
+	readonly={readonly || undefined}
+	invalid={invalid || undefined}
+	required={required || undefined}
+	clearable={clearable || undefined}
+	mono={mono || undefined}
+	description={description}
+	error={error}
+	aria-label={ariaLabel}
+	options={options ? JSON.stringify(options) : undefined}
+	class={extra}
+	set:html={composed}
+	{...rest}
+/>
+
+{!isStatic && <script>import "@xtyle/core/elements";</script>}

package/src/FormGroup.astro

@@ -0,0 +1,71 @@
+---
+import { renderFragmentLight } from "@xtyle/core/elements/ssr";
+
+type Size = "sm" | "md" | "lg";
+
+interface Props {
+	label?: string;
+	description?: string;
+	error?: string;
+	size?: Size;
+	invalid?: boolean;
+	required?: boolean;
+	for?: string;
+	/** Render zero-JS: emit the resolved light-DOM markup but never load the runtime to hydrate it. */
+	static?: boolean;
+	class?: string;
+	/** Any other attribute (`id`, `title`, `data-*`, `aria-*`, …) passes through to the element. */
+	[key: string]: unknown;
+}
+
+const {
+	label = "",
+	description = "",
+	error = "",
+	size = "md",
+	invalid = false,
+	required = false,
+	for: htmlFor,
+	static: isStatic = false,
+	class: extra,
+	...rest
+} = Astro.props;
+
+const seed = Math.random().toString(36).slice(2, 9);
+const labelId = `xtyle-form-group-label-${seed}`;
+const descriptionId = `xtyle-form-group-desc-${seed}`;
+const errorId = `xtyle-form-group-error-${seed}`;
+const controlId = `xtyle-form-group-control-${seed}`;
+
+const bindings = {
+	label,
+	description,
+	error,
+	size,
+	invalid,
+	required,
+	hasFor: htmlFor != null,
+	controlTarget: htmlFor ?? controlId,
+	labelId,
+	descriptionId,
+	errorId,
+};
+const chrome = await renderFragmentLight("form-group", bindings);
+const slotHtml = Astro.slots.has("default") ? await Astro.slots.render("default") : "";
+const composed = chrome.replace("<slot></slot>", () => slotHtml);
+---
+
+<xtyle-form-group
+	label={label}
+	description={description}
+	error={error}
+	size={size}
+	invalid={invalid || undefined}
+	required={required || undefined}
+	for={htmlFor}
+	class={extra}
+	set:html={composed}
+	{...rest}
+/>
+
+{!isStatic && <script>import "@xtyle/core/elements";</script>}

package/src/Grid.astro

@@ -0,0 +1,57 @@
+---
+import { renderFragmentLight } from "@xtyle/core/elements/ssr";
+
+type GridAlign = "start" | "center" | "end" | "stretch";
+
+interface Props {
+	gap?: number;
+	columns?: number;
+	minColWidth?: string;
+	align?: GridAlign;
+	justify?: GridAlign;
+	inline?: boolean;
+	/** Render zero-JS: emit the resolved light-DOM markup but never load the runtime to hydrate it. */
+	static?: boolean;
+	class?: string;
+	/** Any other attribute (`id`, `title`, `data-*`, `aria-*`, …) passes through to the element. */
+	[key: string]: unknown;
+}
+
+const {
+	gap = 4,
+	columns,
+	minColWidth,
+	align,
+	justify,
+	inline = false,
+	static: isStatic = false,
+	class: extra,
+	...rest
+} = Astro.props;
+
+const bindings = {
+	gap,
+	columns: columns ?? null,
+	minColWidth: minColWidth ?? null,
+	align: align ?? null,
+	justify: justify ?? null,
+	inline,
+};
+const chrome = await renderFragmentLight("grid", bindings);
+const slotHtml = Astro.slots.has("default") ? await Astro.slots.render("default") : "";
+const composed = chrome.replace("<slot></slot>", () => slotHtml);
+---
+
+<xtyle-grid
+	gap={gap}
+	columns={columns ?? undefined}
+	min-col-width={minColWidth ?? undefined}
+	align={align ?? undefined}
+	justify={justify ?? undefined}
+	inline={inline || undefined}
+	class={extra}
+	set:html={composed}
+	{...rest}
+/>
+
+{!isStatic && <script>import "@xtyle/core/elements";</script>}

package/src/Heading.astro

@@ -0,0 +1,34 @@
+---
+import { headingSizeForLevel } from "@xtyle/core";
+import { renderFragmentLight } from "@xtyle/core/elements/ssr";
+import type { HeadingLevel, HeadingSize, HeadingTone } from "@xtyle/core";
+
+interface Props {
+	level?: HeadingLevel;
+	size?: HeadingSize;
+	tone?: HeadingTone;
+	/** Render zero-JS: emit the resolved light-DOM markup but never load the runtime to hydrate it. */
+	static?: boolean;
+	class?: string;
+	/** Any other attribute (`id`, `title`, `data-*`, `aria-*`, …) passes through to the element. */
+	[key: string]: unknown;
+}
+
+const { level = 2, size, tone = "default", static: isStatic = false, class: extra, ...rest } =
+	Astro.props;
+
+const resolvedSize = size ?? headingSizeForLevel(level);
+
+const bindings = {
+	level,
+	size: resolvedSize,
+	tone,
+};
+const chrome = await renderFragmentLight("heading", bindings);
+const slotHtml = Astro.slots.has("default") ? await Astro.slots.render("default") : "";
+const composed = chrome.replace("<slot></slot>", () => slotHtml);
+---
+
+<xtyle-heading level={level} size={resolvedSize} tone={tone} class={extra} set:html={composed} {...rest} />
+
+{!isStatic && <script>import "@xtyle/core/elements";</script>}

package/src/Heatmap.astro

@@ -0,0 +1,116 @@
+---
+import { renderFragmentLight } from "@xtyle/core/elements/ssr";
+import { resolveHeatmapColors, resolveHeatmapGlows, resolveHeatmapScale } from "./internal/palette.ts";
+import type { HeatmapScheme } from "@xtyle/core";
+
+interface Props {
+	values?: number[][];
+	/** A second intensity matrix (same shape as `values`) driving each cell's glow halo. */
+	glow?: number[][];
+	rows?: string[];
+	cols?: string[];
+	scheme?: HeatmapScheme;
+	reverse?: boolean;
+	max?: number;
+	/** The glow-channel ceiling a full-strength halo maps to; defaults to the glow data's own max. */
+	glowMax?: number;
+	/** The px blur a full-strength glow halo reaches; defaults to 7. Lower it on a dense grid, raise it on a sparse one. */
+	glowBlur?: number;
+	/** Names the glow metric so its value reaches each cell's accessible name and readout; defaults to "glow". */
+	glowLabel?: string;
+	/** Cells to ring as the current / "now" marker, each a `[rowIndex, colIndex]` pair. */
+	current?: number[][];
+	/** Tint for the current-cell ring: a semantic tone (`success` / `danger` / `warn` / `info` / `neutral`); defaults to accent. */
+	currentTone?: "success" | "danger" | "warn" | "info" | "neutral";
+	/** Pulse the current-cell ring (honors `prefers-reduced-motion`). */
+	currentPulse?: boolean;
+	/** Per-cell hover text (same shape as `values`); overrides a cell's default readout and accessible name. */
+	titles?: string[][];
+	/** Show a color-scale key (five swatches from the ramp with 0..max endpoints) below the grid. */
+	scale?: boolean;
+	showValues?: boolean;
+	/** Make cells actionable: each becomes a `role="button"` that fires `select` on click or Enter/Space. */
+	selectable?: boolean;
+	label?: string;
+	/** Render zero-JS: emit the resolved light-DOM markup but never load the runtime to hydrate it. */
+	static?: boolean;
+	class?: string;
+	/** Any other attribute (`id`, `title`, `data-*`, `aria-*`, …) passes through to the element. */
+	[key: string]: unknown;
+}
+
+const {
+	values = [],
+	glow = [],
+	rows = [],
+	cols = [],
+	scheme = "accent",
+	reverse = false,
+	max,
+	glowMax,
+	glowBlur,
+	glowLabel,
+	current = [],
+	currentTone,
+	currentPulse = false,
+	titles = [],
+	scale = false,
+	showValues = false,
+	selectable = false,
+	label,
+	static: isStatic = false,
+	class: extra,
+	...rest
+} = Astro.props;
+
+const cellColors = await resolveHeatmapColors(scheme, values, reverse, max);
+const cellGlows = await resolveHeatmapGlows(scheme, glow, reverse, glowMax, glowBlur);
+const resolvedGlowLabel = glow.length ? (glowLabel ?? "glow") : null;
+const scaleKey = scale ? await resolveHeatmapScale(scheme, values, reverse, max) : null;
+const bindings = {
+	values,
+	rows,
+	cols,
+	cellColors,
+	cellGlows,
+	glowValues: glow,
+	glowLabel: resolvedGlowLabel,
+	current,
+	currentTone: currentTone ?? null,
+	currentPulse,
+	titles,
+	scale,
+	...(scaleKey ?? {}),
+	showValues,
+	selectable,
+	title: label ?? null,
+	ariaLabel: label ?? null,
+};
+const chrome = await renderFragmentLight("heatmap", bindings);
+---
+
+<xtyle-heatmap
+	values={JSON.stringify(values)}
+	glow={glow.length ? JSON.stringify(glow) : undefined}
+	rows={JSON.stringify(rows)}
+	cols={JSON.stringify(cols)}
+	current={current.length ? JSON.stringify(current) : undefined}
+	titles={titles.length ? JSON.stringify(titles) : undefined}
+	scheme={Array.isArray(scheme) ? JSON.stringify(scheme) : scheme}
+	reverse={reverse || undefined}
+	max={max ?? undefined}
+	glow-max={glowMax ?? undefined}
+	glow-blur={glowBlur ?? undefined}
+	glow-label={glowLabel ?? undefined}
+	current-tone={currentTone ?? undefined}
+	current-pulse={currentPulse || undefined}
+	scale={scale || undefined}
+	show-values={showValues || undefined}
+	selectable={selectable || undefined}
+	label={label}
+	class={extra}
+	set:html={chrome}
+	{...rest}
+/>
+
+{!isStatic && <script>import "@xtyle/core/elements";</script>}

package/src/Hero.astro

@@ -0,0 +1,19 @@
+---
+type HeroAlign = "center" | "start";
+
+interface Props {
+	align?: HeroAlign;
+	split?: boolean;
+	class?: string;
+	/** Any other attribute (`id`, `title`, `data-*`, `aria-*`, …) passes through to the element. */
+	[key: string]: unknown;
+}
+
+const { align = "center", split = false, class: extra, ...rest } = Astro.props;
+---
+
+<xtyle-hero align={align !== "center" ? align : undefined} split={split ? "" : undefined} class={extra} {...rest}>
+	<slot />
+</xtyle-hero>
+
+<script>import "@xtyle/core/elements";</script>

package/src/Icon.astro

@@ -0,0 +1,53 @@
+---
+import { renderFragmentLight } from "@xtyle/core/elements/ssr";
+import { bakeIconMark } from "./internal/palette.ts";
+import { ICON_NAMES, iconClass } from "@xtyle/core";
+import type { FullTone, IconName, IconSize, SeriesScheme } from "@xtyle/core";
+
+interface Props {
+	name: IconName | (string & {});
+	size?: IconSize;
+	tone?: FullTone;
+	/** The series scheme a generated mark's `c3+` color slots draw from. */
+	colors?: SeriesScheme;
+	label?: string;
+	spin?: boolean;
+	/** Render zero-JS: emit the resolved light-DOM markup but never load the runtime to hydrate it. */
+	static?: boolean;
+	class?: string;
+	/** Any other attribute (`id`, `title`, `data-*`, `aria-*`, …) passes through to the element. */
+	[key: string]: unknown;
+}
+
+const {
+	name,
+	size = "md",
+	tone,
+	colors = "accents",
+	label,
+	spin = false,
+	static: isStatic = false,
+	class: extra,
+	...rest
+} = Astro.props;
+
+// A functional glyph is looked up; any other name is offered to the mark generators and baked when one claims it.
+const isGlyph = typeof name !== "string" || (ICON_NAMES as readonly string[]).includes(name);
+const mark = isGlyph ? null : await bakeIconMark(name, colors, iconClass({ size, tone, spin }));
+const composed =
+	mark != null ? `<span data-root data-icon>${mark}</span>` : await renderFragmentLight("icon", { name, size, tone, label, spin });
+---
+
+<xtyle-icon
+	name={name}
+	size={size}
+	tone={tone}
+	colors={mark != null ? colors : undefined}
+	label={label}
+	spin={spin ? "" : undefined}
+	class={extra}
+	set:html={composed}
+	{...rest}
+/>
+
+{!isStatic && <script>import "@xtyle/core/elements";</script>}

package/src/Image.astro

@@ -0,0 +1,56 @@
+---
+import { renderFragmentLight } from "@xtyle/core/elements/ssr";
+
+type ImageFit = "cover" | "contain";
+type ImageRadius = "none" | "sm" | "md" | "lg";
+type ImageLoading = "lazy" | "eager";
+
+interface Props {
+	src?: string;
+	alt?: string;
+	ratio?: string;
+	fit?: ImageFit;
+	radius?: ImageRadius;
+	loading?: ImageLoading;
+	lightbox?: boolean;
+	caption?: string;
+	/** Render zero-JS: emit the resolved light-DOM markup but never load the runtime to hydrate it. */
+	static?: boolean;
+	class?: string;
+	/** Any other attribute (`id`, `title`, `data-*`, `aria-*`, …) passes through to the element. */
+	[key: string]: unknown;
+}
+
+const {
+	src,
+	alt = "",
+	ratio,
+	fit = "cover",
+	radius = "md",
+	loading = "lazy",
+	lightbox = false,
+	caption,
+	static: isStatic = false,
+	class: extra,
+	...rest
+} = Astro.props;
+
+const bindings = { src, alt, ratio, fit, radius, loading, caption };
+const composed = await renderFragmentLight("image", bindings);
+---
+
+<xtyle-image
+	src={src}
+	alt={alt}
+	ratio={ratio}
+	fit={fit}
+	radius={radius}
+	loading={loading}
+	caption={caption}
+	lightbox={lightbox ? "" : undefined}
+	class={extra}
+	set:html={composed}
+	{...rest}
+/>
+
+{!isStatic && <script>import "@xtyle/core/elements";</script>}

package/src/Kbd.astro

@@ -0,0 +1,27 @@
+---
+import { renderFragmentLight } from "@xtyle/core/elements/ssr";
+
+import type { FullTone as KbdTone } from "@xtyle/core";
+type KbdSize = "sm" | "md" | "lg";
+
+interface Props {
+	size?: KbdSize;
+	tone?: KbdTone;
+	/** Render zero-JS: emit the resolved light-DOM markup but never load the runtime to hydrate it. */
+	static?: boolean;
+	class?: string;
+	/** Any other attribute (`id`, `title`, `data-*`, `aria-*`, …) passes through to the element. */
+	[key: string]: unknown;
+}
+
+const { size = "md", tone, static: isStatic = false, class: extra, ...rest } = Astro.props;
+
+const bindings = { size, tone };
+const chrome = await renderFragmentLight("kbd", bindings);
+const slotHtml = Astro.slots.has("default") ? await Astro.slots.render("default") : "";
+const composed = chrome.replace("<slot></slot>", () => slotHtml);
+---
+
+<xtyle-kbd size={size} tone={tone} class={extra} set:html={composed} {...rest} />
+
+{!isStatic && <script>import "@xtyle/core/elements";</script>}