@xtyle/astro 0.5.0

package/README.md

@@ -0,0 +1,42 @@
+# @xtyle/astro
+
+[![npm](https://img.shields.io/npm/v/@xtyle/astro?label=npm)](https://www.npmjs.com/package/@xtyle/astro)
+[![docs](https://img.shields.io/badge/docs-xtyle.dev-blue)](https://xtyle.dev)
+[![license](https://img.shields.io/badge/license-MIT-green)](https://opensource.org/license/mit)
+
+Zero-JS Astro 6 components that emit semantic HTML against the xtyle component classes,
+the SSR binding of the [`@xtyle/core`](https://www.npmjs.com/package/@xtyle/core) component
+contract. Each component server-renders the matching markup and ships **no client
+JavaScript** unless that component genuinely needs it.
+
+## Install
+
+```sh
+npm install @xtyle/astro @xtyle/core
+```
+
+`astro@^6` is a peer dependency; `@xtyle/core` (pulled in automatically) provides the
+markup contract and the derivation engine.
+
+## Usage
+
+```astro
+---
+import Button from "@xtyle/astro/Button.astro";
+import Card from "@xtyle/astro/Card.astro";
+---
+
+<Card>
+  <Button tone="accent">Save</Button>
+</Card>
+```
+
+Components are styled entirely by **design tokens**, the CSS custom properties a xtyle
+*algorithm* derives. Emit a theme to CSS (via the `xtyle` CLI in `@xtyle/core`) and drop it
+on `:root`; every component themes with it, with nothing running at runtime. See
+[`@xtyle/core`](https://www.npmjs.com/package/@xtyle/core) for deriving a theme, and
+[xtyle.dev](https://xtyle.dev) for the full component reference.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,25 @@
+{
+	"name": "@xtyle/astro",
+	"version": "0.5.0",
+	"description": "Zero-JS Astro components that emit semantic HTML against the xtyle component classes; the SSR binding of the component contract.",
+	"type": "module",
+	"license": "MIT",
+	"exports": {
+		"./*": "./src/*"
+	},
+	"files": [
+		"src",
+		"README.md"
+	],
+	"dependencies": {
+		"@xtyle/core": "^0.5.0"
+	},
+	"peerDependencies": {
+		"astro": "^6.0.0"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/nekoyoubi/xtyle.git",
+		"directory": "packages/astro"
+	}
+}

package/src/Accordion.astro

@@ -0,0 +1,79 @@
+---
+import { type AccordionSection } from "@xtyle/core/markup";
+import { renderFragmentLight } from "@xtyle/core/elements/ssr";
+
+type Size = "sm" | "md" | "lg";
+
+interface Props {
+	items?: AccordionSection[];
+	multiple?: boolean;
+	size?: Size;
+	headingLevel?: 1 | 2 | 3 | 4 | 5 | 6;
+	/** 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 {
+	items,
+	multiple = false,
+	size = "md",
+	headingLevel,
+	static: isStatic = false,
+	class: extra,
+	...rest
+} = Astro.props;
+
+const sections = items ?? [];
+const uid = `xtyle-accordion-${Math.random().toString(36).slice(2, 9)}`;
+
+const openKeys: string[] = [];
+sections.forEach((section, i) => {
+	if (!section.open) return;
+	const key = section.value ?? String(i);
+	if (multiple) openKeys.push(key);
+	else if (openKeys.length === 0) openKeys.push(key);
+});
+
+const bindings = {
+	sections: sections.map((section, i) => ({
+		header: section.header,
+		panel: section.panel,
+		panelSlot: section.panelSlot,
+		value: section.value ?? String(i),
+		disabled: section.disabled,
+	})),
+	openKeys,
+	size,
+	headingLevel,
+	uid,
+};
+// Two authoring modes. items-mode renders the whole structure light from `bindings` and ships no
+// children. The advanced slotted mode pairs the consumer's `slot="header"`/`slot="panel"` children
+// by order, so they must survive *individually* (with their slot attributes) — Astro's `<slot
+// name>` passthrough keeps them intact, and the element builds the structure from them on connect.
+const useItems = sections.length > 0;
+const light = useItems ? await renderFragmentLight("accordion", bindings) : "";
+---
+
+{useItems ? (
+	<xtyle-accordion
+		multiple={multiple || undefined}
+		size={size}
+		heading-level={headingLevel}
+		items={JSON.stringify(items)}
+		class={extra}
+		set:html={light}
+		{...rest}
+	/>
+) : (
+	<xtyle-accordion multiple={multiple || undefined} size={size} heading-level={headingLevel} class={extra} {...rest}>
+		<slot name="header" />
+		<slot name="panel" />
+		<slot />
+	</xtyle-accordion>
+)}
+
+{!isStatic && <script>import "@xtyle/core/elements";</script>}

package/src/Alert.astro

@@ -0,0 +1,57 @@
+---
+import { renderFragmentLight, composeFallbackSlot } from "@xtyle/core/elements/ssr";
+import type { FullTone } from "@xtyle/core";
+
+type AlertSeverity = "success" | "warn" | "danger" | "info";
+type AlertVariant = "soft" | "solid";
+
+interface Props {
+	/** Color — any semantic role, accent variant, or named hue. Defaults to the severity color. */
+	tone?: FullTone;
+	/** Meaning — drives the glyph + politeness, independent of color. Omit for a color-only notice. */
+	severity?: AlertSeverity;
+	variant?: AlertVariant;
+	dismissible?: boolean;
+	dismissLabel?: 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 {
+	tone,
+	severity,
+	variant = "soft",
+	dismissible = false,
+	dismissLabel = "Dismiss",
+	static: isStatic = false,
+	class: extra,
+	...rest
+} = Astro.props;
+
+const bindings = { tone, severity, variant, dismissible, dismissLabel };
+const light = await renderFragmentLight("alert", bindings);
+const iconHtml = Astro.slots.has("icon") ? await Astro.slots.render("icon") : null;
+const titleHtml = Astro.slots.has("title") ? await Astro.slots.render("title") : "";
+const messageHtml = Astro.slots.has("default") ? await Astro.slots.render("default") : "";
+const actionsHtml = Astro.slots.has("actions") ? await Astro.slots.render("actions") : "";
+const composed = composeFallbackSlot(light, "icon", iconHtml)
+	.replace('<slot name="title"></slot>', () => titleHtml)
+	.replace('<slot name="actions"></slot>', () => actionsHtml)
+	.replace("<slot></slot>", () => messageHtml);
+---
+
+<xtyle-alert
+	tone={tone}
+	severity={severity}
+	variant={variant}
+	dismissible={dismissible || undefined}
+	dismiss-label={dismissLabel}
+	class={extra}
+	set:html={composed}
+	{...rest}
+/>
+
+{!isStatic && <script>import "@xtyle/core/elements";</script>}

package/src/AppShell.astro

@@ -0,0 +1,97 @@
+---
+import { renderFragmentLight } from "@xtyle/core/elements/ssr";
+
+interface Props {
+	skipLink?: string | boolean;
+	/** Initial width of the left rail; sets `--xtyle-app-left` server-side so the grid doesn't reflow on hydration. Number → px. */
+	leftSize?: number | string;
+	/** Initial width of the right rail; sets `--xtyle-app-right` server-side so the grid doesn't reflow on hydration. Number → px. */
+	rightSize?: number | string;
+	/** Make the left / right rail user-resizable: a drag handle, arrow-key nudges, and a double-click reset to `leftSize` / `rightSize`. Needs the hydrated runtime. */
+	leftResizable?: boolean;
+	rightResizable?: boolean;
+	/** Clamp for the resizable rails, in px. */
+	leftMin?: number;
+	leftMax?: number;
+	rightMin?: number;
+	rightMax?: number;
+	/** The `id` of the `<main>` region and the skip link's target. Override when more than one shell renders on a page so the ids stay unique. */
+	mainId?: string;
+	/** 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 {
+	skipLink,
+	leftSize,
+	rightSize,
+	leftResizable,
+	rightResizable,
+	leftMin,
+	leftMax,
+	rightMin,
+	rightMax,
+	mainId = "main",
+	static: isStatic = false,
+	class: extra,
+	...rest
+} = Astro.props;
+
+const hasLeft = Astro.slots.has("left");
+const hasRight = Astro.slots.has("right");
+const hasToolbar = Astro.slots.has("toolbar");
+const hasStatusbar = Astro.slots.has("statusbar");
+const showSkip = skipLink !== undefined;
+const skipText = typeof skipLink === "string" && skipLink.length > 0 ? skipLink : "Skip to main content";
+
+const railSize = (v: number | string): string => (typeof v === "number" ? `${v}px` : v);
+const bodyStyle =
+	[
+		leftSize !== undefined ? `--xtyle-app-left: ${railSize(leftSize)}` : null,
+		rightSize !== undefined ? `--xtyle-app-right: ${railSize(rightSize)}` : null,
+	]
+		.filter(Boolean)
+		.join("; ") || null;
+
+const bindings = {
+	skipLink: showSkip,
+	skipLinkText: skipText,
+	bodyStyle,
+	mainId,
+	leftResizable: Boolean(leftResizable),
+	rightResizable: Boolean(rightResizable),
+};
+const light = await renderFragmentLight("app-shell", bindings);
+const toolbarHtml = hasToolbar ? await Astro.slots.render("toolbar") : "";
+const leftHtml = hasLeft ? await Astro.slots.render("left") : "";
+const rightHtml = hasRight ? await Astro.slots.render("right") : "";
+const statusbarHtml = hasStatusbar ? await Astro.slots.render("statusbar") : "";
+const defaultHtml = Astro.slots.has("default") ? await Astro.slots.render("default") : "";
+const composed = light
+	.replace('<slot name="toolbar"></slot>', () => toolbarHtml)
+	.replace('<slot name="left"></slot>', () => leftHtml)
+	.replace('<slot name="right"></slot>', () => rightHtml)
+	.replace('<slot name="statusbar"></slot>', () => statusbarHtml)
+	.replace("<slot></slot>", () => defaultHtml);
+---
+
+<xtyle-app-shell
+	skip-link={typeof skipLink === "string" ? skipLink : showSkip ? "" : undefined}
+	left-size={leftSize === undefined ? undefined : String(leftSize)}
+	right-size={rightSize === undefined ? undefined : String(rightSize)}
+	left-resizable={leftResizable ? "" : undefined}
+	right-resizable={rightResizable ? "" : undefined}
+	left-min={leftMin === undefined ? undefined : String(leftMin)}
+	left-max={leftMax === undefined ? undefined : String(leftMax)}
+	right-min={rightMin === undefined ? undefined : String(rightMin)}
+	right-max={rightMax === undefined ? undefined : String(rightMax)}
+	main-id={mainId === "main" ? undefined : mainId}
+	class={extra}
+	set:html={composed}
+	{...rest}
+/>
+
+{!isStatic && <script>import "@xtyle/core/elements";</script>}

package/src/Avatar.astro

@@ -0,0 +1,71 @@
+---
+import { renderFragmentLight } from "@xtyle/core/elements/ssr";
+
+import type { Tone, FullTone as BadgeTone } from "@xtyle/core";
+type AvatarSize = "sm" | "md" | "lg" | "xl";
+type AvatarShape = "circle" | "square";
+
+interface Props {
+	src?: string;
+	alt?: string;
+	tone?: BadgeTone;
+	size?: AvatarSize;
+	shape?: AvatarShape;
+	status?: Tone;
+	statusLabel?: string;
+	/** Breathe the status dot for a live / online presence: a bare `true` pulses slow, `"fast"` quick. */
+	pulse?: boolean | "slow" | "fast";
+	/** 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 = "",
+	tone = "neutral",
+	size = "md",
+	shape = "circle",
+	status,
+	statusLabel,
+	pulse,
+	static: isStatic = false,
+	class: extra,
+	...rest
+} = Astro.props;
+
+const bindings = {
+	src: src ?? null,
+	alt,
+	tone,
+	size,
+	shape,
+	status: status ?? null,
+	statusLabel: statusLabel ?? null,
+	pulse: pulse ?? null,
+};
+const chrome = await renderFragmentLight("avatar", bindings);
+const iconHtml = Astro.slots.has("icon") ? await Astro.slots.render("icon") : "";
+const bodyHtml = Astro.slots.has("default") ? await Astro.slots.render("default") : "";
+const composed = chrome
+	.replace('<slot name="icon"></slot>', () => iconHtml)
+	.replace("<slot></slot>", () => bodyHtml);
+---
+
+<xtyle-avatar
+	src={src ?? undefined}
+	alt={alt}
+	tone={tone}
+	size={size}
+	shape={shape}
+	status={status ?? undefined}
+	status-label={statusLabel ?? undefined}
+	pulse={pulse === true ? "" : pulse || undefined}
+	class={extra}
+	set:html={composed}
+	{...rest}
+/>
+
+{!isStatic && <script>import "@xtyle/core/elements";</script>}

package/src/AvatarGroup.astro

@@ -0,0 +1,44 @@
+---
+import { renderFragmentLight } from "@xtyle/core/elements/ssr";
+
+type AvatarGroupSize = "sm" | "md" | "lg" | "xl";
+type AvatarGroupSpacing = "snug" | "normal" | "loose";
+
+interface Props {
+	size?: AvatarGroupSize;
+	spacing?: AvatarGroupSpacing;
+	/** How many avatars beyond the shown ones to summarize as a trailing `+N` chip. */
+	overflow?: number;
+	/** Accessible name for the group (a list of people). */
+	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 { size, spacing, overflow, label, static: isStatic = false, class: extra, ...rest } = Astro.props;
+
+const bindings = {
+	size: size ?? null,
+	spacing: spacing ?? null,
+	overflow: overflow ?? 0,
+	label: label ?? null,
+};
+const chrome = await renderFragmentLight("avatar-group", bindings);
+const slotHtml = Astro.slots.has("default") ? await Astro.slots.render("default") : "";
+const composed = chrome.replace("<slot></slot>", () => slotHtml);
+---
+
+<xtyle-avatar-group
+	size={size}
+	spacing={spacing}
+	overflow={overflow ?? undefined}
+	label={label}
+	class={extra}
+	set:html={composed}
+	{...rest}
+/>
+
+{!isStatic && <script>import "@xtyle/core/elements";</script>}

package/src/Badge.astro

@@ -0,0 +1,73 @@
+---
+import { renderFragmentLight } from "@xtyle/core/elements/ssr";
+
+import type { FullTone as BadgeTone } from "@xtyle/core";
+type Size = "sm" | "md" | "lg";
+type BadgeVariant = "solid" | "soft" | "outline";
+
+interface Props {
+	variant?: BadgeVariant;
+	tone?: BadgeTone;
+	size?: Size;
+	dot?: boolean;
+	pulse?: boolean | "slow" | "fast";
+	count?: string | number;
+	removable?: boolean;
+	removeLabel?: 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 {
+	variant = "soft",
+	tone = "neutral",
+	size = "md",
+	dot = false,
+	pulse,
+	count,
+	removable = false,
+	removeLabel,
+	static: isStatic = false,
+	class: extra,
+	...rest
+} = Astro.props;
+
+const slotHtml = Astro.slots.has("default") ? await Astro.slots.render("default") : "";
+// Compose the dismiss button's accessible name from the label text when the consumer didn't name
+// it — so a zero-JS (`static`) removable badge still announces "Remove <text>" instead of a bare
+// "Remove". The runtime composes this client-side from the slot, but `static` never loads it.
+const slotText = slotHtml.replace(/<[^>]*>/g, "").trim();
+const resolvedRemoveLabel = removeLabel ?? (removable && slotText ? `Remove ${slotText}` : undefined);
+
+const bindings = {
+	variant,
+	tone,
+	size,
+	dot,
+	pulse: pulse === true ? "slow" : pulse || null,
+	count: count ?? null,
+	removable,
+	removeLabel: resolvedRemoveLabel,
+};
+const chrome = await renderFragmentLight("badge", bindings);
+const composed = chrome.replace("<slot></slot>", () => slotHtml);
+---
+
+<xtyle-badge
+	variant={variant}
+	tone={tone}
+	size={size}
+	dot={dot || undefined}
+	pulse={pulse === true ? "slow" : pulse || undefined}
+	count={count !== undefined && count !== null && count !== "" ? String(count) : undefined}
+	removable={removable || undefined}
+	remove-label={resolvedRemoveLabel}
+	class={extra}
+	set:html={composed}
+	{...rest}
+/>
+
+{!isStatic && <script>import "@xtyle/core/elements";</script>}

package/src/Bar.astro

@@ -0,0 +1,83 @@
+---
+import { renderFragmentLight } from "@xtyle/core/elements/ssr";
+import { resolveSeriesColorsFor } from "./internal/palette.ts";
+import type { BarSeries, BarScheme } from "@xtyle/core";
+
+interface Props {
+	series?: BarSeries[];
+	categories?: string[];
+	scheme?: BarScheme;
+	reverse?: boolean;
+	colorBy?: "series" | "category";
+	orientation?: "vertical" | "horizontal";
+	stacked?: boolean;
+	showValues?: boolean;
+	legend?: boolean;
+	height?: number;
+	label?: string;
+	/** Make bars actionable: each becomes a `role="button"` that fires `select` on click or Enter/Space. */
+	selectable?: 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 {
+	series = [],
+	categories = [],
+	scheme = "accents",
+	reverse = false,
+	colorBy,
+	orientation = "vertical",
+	stacked = false,
+	showValues = false,
+	legend = true,
+	height = 320,
+	label,
+	selectable = false,
+	static: isStatic = false,
+	class: extra,
+	...rest
+} = Astro.props;
+
+const resolvedColorBy = colorBy ?? (series.length <= 1 ? "category" : "series");
+const colorItems = resolvedColorBy === "category" ? categories.map(() => ({})) : series;
+const colors = await resolveSeriesColorsFor(scheme, colorItems, reverse);
+const bindings = {
+	series,
+	categories,
+	colors,
+	colorBy: resolvedColorBy,
+	orientation,
+	stacked,
+	showValues,
+	legend,
+	height,
+	title: label ?? null,
+	ariaLabel: label ?? null,
+	selectable,
+};
+const chrome = await renderFragmentLight("bar", bindings);
+---
+
+<xtyle-bar
+	series={JSON.stringify(series)}
+	categories={JSON.stringify(categories)}
+	scheme={Array.isArray(scheme) ? JSON.stringify(scheme) : scheme}
+	reverse={reverse || undefined}
+	color-by={colorBy}
+	orientation={orientation === "horizontal" ? "horizontal" : undefined}
+	stacked={stacked || undefined}
+	show-values={showValues || undefined}
+	legend={legend ? undefined : "false"}
+	selectable={selectable || undefined}
+	height={height}
+	label={label}
+	class={extra}
+	set:html={chrome}
+	{...rest}
+/>
+
+{!isStatic && <script>import "@xtyle/core/elements";</script>}

package/src/Breadcrumb.astro

@@ -0,0 +1,54 @@
+---
+import { type BreadcrumbItem } from "@xtyle/core/markup";
+import { renderFragmentLight } from "@xtyle/core/elements/ssr";
+import type { Size, FullTone } from "@xtyle/core";
+
+interface Props {
+	items?: BreadcrumbItem[];
+	separator?: string;
+	tone?: FullTone;
+	size?: Size;
+	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 {
+	items,
+	separator = "/",
+	tone = "accent",
+	size = "md",
+	label = "Breadcrumb",
+	static: isStatic = false,
+	class: extra,
+	...rest
+} = Astro.props;
+
+const bindings = {
+	items: items ?? [],
+	separator,
+	tone,
+	size,
+	label,
+};
+const light = await renderFragmentLight("breadcrumb", bindings);
+// only the no-items (consumer-slotted) render carries a marker; the items render fills the list
+const slotHtml = Astro.slots.has("default") ? await Astro.slots.render("default") : "";
+const composed = light.replace("<slot></slot>", () => slotHtml);
+---
+
+<xtyle-breadcrumb
+	items={items ? JSON.stringify(items) : undefined}
+	separator={separator}
+	tone={tone}
+	size={size}
+	label={label}
+	class={extra}
+	set:html={composed}
+	{...rest}
+/>
+
+{!isStatic && <script>import "@xtyle/core/elements";</script>}