@sepale/components 0.0.0-stage → 0.1.0

package/dist/components/Stat.svelte

@@ -0,0 +1,71 @@
+<script module lang="ts">
+	/** What .stat is made of, classified. */
+	export const PREFIX = 'stat';
+
+	export const AXES = {
+		size: ['xs', 'sm', 'md', 'lg', 'xl']
+	} as const;
+
+	export const FLAGS = {} as const;
+	export const PARTS = ['title', 'value', 'desc', 'figure', 'actions'] as const;
+</script>
+
+<script lang="ts">
+	/**
+	 * A figure worth a glance: a title, a value, a description, and optionally
+	 * a figure on the side and a row of actions.
+	 *
+	 * The three text parts take a string — the common case — or a snippet.
+	 * Put several in a `Stats` to line them up in one frame.
+	 */
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { applyAxes, cx, type AxisProps } from '../variants.js';
+
+	/* `title` is an HTML attribute too, and a tooltip is not a label — so the
+	   DOM one is dropped rather than shadowed silently. */
+	interface Props
+		extends AxisProps<typeof AXES, typeof FLAGS, typeof PREFIX>,
+			Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
+		/** The small label above the value. */
+		title?: string | Snippet;
+		/** The number itself. */
+		value?: string | Snippet;
+		/** A line under the value: a trend, a period. */
+		desc?: string | Snippet;
+		/** An icon or a picture, beside the text. */
+		figure?: Snippet;
+		/** A row of buttons, under the text. */
+		actions?: Snippet;
+		class?: string;
+		/** Anything else, after the description. */
+		children?: Snippet;
+	}
+
+	let {
+		title,
+		value,
+		desc,
+		figure,
+		actions,
+		class: klass = '',
+		children,
+		...axes
+	}: Props = $props();
+
+	let applied = $derived(applyAxes(PREFIX, AXES, FLAGS, axes));
+	let classes = $derived(cx(PREFIX, applied.classes, klass));
+</script>
+
+{#snippet text(part: string | Snippet)}
+	{#if typeof part === 'string'}{part}{:else}{@render part()}{/if}
+{/snippet}
+
+<div class={classes} {...applied.rest}>
+	{#if figure}<div class="stat-figure">{@render figure()}</div>{/if}
+	{#if title}<div class="stat-title">{@render text(title)}</div>{/if}
+	{#if value}<div class="stat-value">{@render text(value)}</div>{/if}
+	{#if desc}<div class="stat-desc">{@render text(desc)}</div>{/if}
+	{@render children?.()}
+	{#if actions}<div class="stat-actions">{@render actions()}</div>{/if}
+</div>

package/dist/components/Stat.svelte.d.ts

@@ -0,0 +1,35 @@
+/** What .stat is made of, classified. */
+export declare const PREFIX = "stat";
+export declare const AXES: {
+    readonly size: readonly ["xs", "sm", "md", "lg", "xl"];
+};
+export declare const FLAGS: {};
+export declare const PARTS: readonly ["title", "value", "desc", "figure", "actions"];
+/**
+     * A figure worth a glance: a title, a value, a description, and optionally
+     * a figure on the side and a row of actions.
+     *
+     * The three text parts take a string — the common case — or a snippet.
+     * Put several in a `Stats` to line them up in one frame.
+     */
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import { type AxisProps } from '../variants.js';
+interface Props extends AxisProps<typeof AXES, typeof FLAGS, typeof PREFIX>, Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
+    /** The small label above the value. */
+    title?: string | Snippet;
+    /** The number itself. */
+    value?: string | Snippet;
+    /** A line under the value: a trend, a period. */
+    desc?: string | Snippet;
+    /** An icon or a picture, beside the text. */
+    figure?: Snippet;
+    /** A row of buttons, under the text. */
+    actions?: Snippet;
+    class?: string;
+    /** Anything else, after the description. */
+    children?: Snippet;
+}
+declare const Stat: import("svelte").Component<Props, {}, "">;
+type Stat = ReturnType<typeof Stat>;
+export default Stat;

package/dist/components/Stats.svelte

@@ -0,0 +1,38 @@
+<script module lang="ts">
+	/** What .stats is made of, classified. */
+	export const PREFIX = 'stats';
+
+	export const AXES = {
+		direction: ['horizontal', 'vertical']
+	} as const;
+
+	export const FLAGS = {} as const;
+	export const PARTS = [] as const;
+</script>
+
+<script lang="ts">
+	/**
+	 * Several stats in one frame, a divider between each. The stats inside put
+	 * their own frame down; a row by default.
+	 */
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { applyAxes, cx, type AxisProps } from '../variants.js';
+
+	interface Props extends AxisProps<typeof AXES, typeof FLAGS, typeof PREFIX>, HTMLAttributes<HTMLDivElement> {
+		class?: string;
+		/** The `Stat`s. */
+		children?: Snippet;
+	}
+
+	let {
+		class: klass = '',
+		children,
+		...axes
+	}: Props = $props();
+
+	let applied = $derived(applyAxes(PREFIX, AXES, FLAGS, axes));
+	let classes = $derived(cx(PREFIX, applied.classes, klass));
+</script>
+
+<div class={classes} {...applied.rest}>{@render children?.()}</div>

package/dist/components/Stats.svelte.d.ts

@@ -0,0 +1,22 @@
+/** What .stats is made of, classified. */
+export declare const PREFIX = "stats";
+export declare const AXES: {
+    readonly direction: readonly ["horizontal", "vertical"];
+};
+export declare const FLAGS: {};
+export declare const PARTS: readonly [];
+/**
+     * Several stats in one frame, a divider between each. The stats inside put
+     * their own frame down; a row by default.
+     */
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import { type AxisProps } from '../variants.js';
+interface Props extends AxisProps<typeof AXES, typeof FLAGS, typeof PREFIX>, HTMLAttributes<HTMLDivElement> {
+    class?: string;
+    /** The `Stat`s. */
+    children?: Snippet;
+}
+declare const Stats: import("svelte").Component<Props, {}, "">;
+type Stats = ReturnType<typeof Stats>;
+export default Stats;

package/dist/components/Steps.svelte

@@ -0,0 +1,204 @@
+<script module lang="ts">
+	/** What .steps is made of, classified. The props follow the
+	    families the project registers (variants.ts, ADR 0015). */
+	export const PREFIX = 'steps';
+
+	export const AXES = {
+		direction: ['horizontal', 'vertical'],
+		color: ['primary', 'secondary', 'accent', 'neutral', 'info', 'success', 'warning', 'error'],
+		size: ['xs', 'sm', 'md', 'lg', 'xl']
+	} as const;
+
+	export const FLAGS = {
+		compact: 'No markers nor labels: the bars, and a heading above them (small screens).'
+	} as const;
+	export const PARTS = [
+		'heading',
+		'list',
+		'item',
+		'track',
+		'marker',
+		'segment',
+		'label',
+		'issue',
+		'sublabel'
+	] as const;
+
+	/** A stage of the journey. Its sub-steps go one level deep, no further. */
+	export interface Step {
+		id: string | number;
+		label?: string;
+		/** The sub-steps. A step without any is a stage of its own. */
+		steps?: Step[];
+		/** Declared done by the app. Visiting a step does not complete it. */
+		complete?: boolean;
+		/** Shown once the step has been reached. */
+		error?: string;
+		warning?: string;
+	}
+
+	/** current · visited (reached before) · complete (declared) · unknown (not reached). */
+	export type StepState = 'current' | 'visited' | 'complete' | 'unknown';
+</script>
+
+<script lang="ts">
+	/**
+	 * Where the user is in a journey: one column per step, one bar per sub-step.
+	 *
+	 * The component moves nothing: a click calls `onStep` with the step, and
+	 * the app decides whether to change `current`. A step is clickable once it
+	 * has been reached (current, visited or complete) — a step's own marker
+	 * leads to its first sub-step. `clickable={false}` or `disabled` turns that
+	 * off.
+	 *
+	 * `explored` is the first leaf never reached; every leaf before it counts
+	 * as visited. Without it, everything up to `current` does.
+	 */
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { applyAxes, cx, type AxisProps } from '../variants.js';
+
+	interface Props extends AxisProps<typeof AXES, typeof FLAGS, typeof PREFIX>, Omit<HTMLAttributes<HTMLElement>, 'color'> {
+		steps: Step[];
+		/** The id of the current leaf (a sub-step, or a step without any). */
+		current?: Step['id'];
+		/** The id of the first leaf never reached. */
+		explored?: Step['id'];
+		/** Reached steps answer clicks. */
+		clickable?: boolean;
+		disabled?: boolean;
+		/** A reached step was clicked: a leaf, or the first leaf of a step. */
+		onStep?: (step: Step) => void;
+		/** The line above the bars in compact mode. Defaults to "label · sub-label   n/total". */
+		heading?: Snippet<[{ step: Step | undefined; parent: Step | undefined; index: number; total: number }]>;
+		/** The nav's accessible name. */
+		label?: string;
+		class?: string;
+	}
+
+	// The axes are deliberately NOT destructured: they travel in `axes` and are
+	// resolved by name, so an axis a family drops changes nothing down here.
+	let {
+		steps,
+		current,
+		explored,
+		clickable = true,
+		disabled = false,
+		onStep,
+		heading,
+		label = 'Progress',
+		class: klass = '',
+		...axes
+	}: Props = $props();
+
+	let applied = $derived(applyAxes(PREFIX, AXES, FLAGS, axes));
+	let classes = $derived(cx(PREFIX, applied.classes, klass));
+	/* Read back from the classes, the one place the axes are resolved. */
+	let condensed = $derived(classes.includes(`${PREFIX}-compact`));
+
+	const leavesOf = (s: Step) => (s.steps?.length ? s.steps : [s]);
+	let leaves = $derived(steps.flatMap(leavesOf));
+	let currentAt = $derived(leaves.findIndex((l) => l.id === current));
+	let exploredAt = $derived.by(() => {
+		const i = explored === undefined ? -1 : leaves.findIndex((l) => l.id === explored);
+		return i >= 0 ? i : currentAt + 1;
+	});
+
+	function leafState(leaf: Step): StepState {
+		if (leaf.id === current) return 'current';
+		if (leaf.complete) return 'complete';
+		return leaves.indexOf(leaf) < exploredAt ? 'visited' : 'unknown';
+	}
+
+	function stepState(step: Step): StepState {
+		const states = leavesOf(step).map(leafState);
+		if (states.includes('current')) return 'current';
+		if (states.every((s) => s === 'complete')) return 'complete';
+		return states.some((s) => s !== 'unknown') ? 'visited' : 'unknown';
+	}
+
+	/** The issue a reached leaf carries. */
+	const issueOf = (leaf: Step, state: StepState) =>
+		state === 'unknown' ? undefined : leaf.error ? 'error' : leaf.warning ? 'warning' : undefined;
+
+	const reachable = (state: StepState) => clickable && !disabled && state !== 'unknown';
+
+	let currentParent = $derived(steps.find((s) => leavesOf(s).some((l) => l.id === current)));
+	let currentLeaf = $derived(leaves[currentAt]);
+</script>
+
+{#snippet issueIcon(kind: 'error' | 'warning', text: string)}
+	<span class="steps-issue" data-issue={kind} title={text} role="img" aria-label={text}>
+		<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round">
+			<path d="M12 3 2 20h20L12 3Z" /><path d="M12 10v4M12 17h.01" />
+		</svg>
+	</span>
+{/snippet}
+
+<nav {...applied.rest} class={classes} aria-label={label}>
+	{#if condensed}
+		<div class="steps-heading">
+			{#if heading}
+				{@render heading({ step: currentLeaf, parent: currentParent, index: steps.indexOf(currentParent!) + 1, total: steps.length })}
+			{:else}
+				<span>
+					{currentParent?.label ?? ''}{#if currentParent && currentLeaf && currentLeaf !== currentParent && currentLeaf.label}{' · '}{currentLeaf.label}{/if}
+				</span>
+				<span>{steps.indexOf(currentParent!) + 1}/{steps.length}</span>
+			{/if}
+		</div>
+	{/if}
+	<ol class="steps-list">
+		{#each steps as step, n (step.id)}
+			{@const state = stepState(step)}
+			{@const own = leavesOf(step)}
+			{@const issues = own
+				.map((l) => ({ kind: issueOf(l, leafState(l)), text: l.error ?? l.warning ?? '' }))
+				.filter((i) => i.kind)}
+			<li class="steps-item" data-state={state}>
+				<div class="steps-track">
+					{#if !condensed}
+						<button
+							type="button"
+							class="steps-marker"
+							aria-label={step.label ?? `${n + 1}`}
+							disabled={!reachable(state)}
+							onclick={() => onStep?.(own[0]!)}
+						>
+							<svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="3" stroke-linecap="round" stroke-linejoin="round"><path d="m5 12.5 4.5 4.5L19 7.5" /></svg>
+						</button>
+					{/if}
+					{#each own as leaf, i (leaf.id)}
+						{@const ls = leafState(leaf)}
+						<button
+							type="button"
+							class="steps-segment"
+							data-state={ls}
+							data-issue={issueOf(leaf, ls)}
+							title={(issueOf(leaf, ls) && (leaf.error ?? leaf.warning)) || leaf.label}
+							aria-label={leaf.label ?? `${n + 1}${own.length > 1 ? `.${i + 1}` : ''}`}
+							aria-current={ls === 'current' ? 'step' : undefined}
+							disabled={!reachable(ls)}
+							onclick={() => onStep?.(leaf)}
+						>
+							<span></span>
+						</button>
+					{/each}
+				</div>
+				{#if !condensed && (step.label || issues.length)}
+					<p class="steps-label">
+						{#if step.label}<span>{step.label}</span>{/if}
+						{#if issues.some((i) => i.kind === 'error')}
+							{@render issueIcon('error', issues.filter((i) => i.kind === 'error').map((i) => i.text).join('\n'))}
+						{:else if issues.length}
+							{@render issueIcon('warning', issues.map((i) => i.text).join('\n'))}
+						{/if}
+					</p>
+				{/if}
+				{#if !condensed && state === 'current' && own.length > 1 && currentLeaf?.label}
+					<p class="steps-sublabel">{currentLeaf.label}</p>
+				{/if}
+			</li>
+		{/each}
+	</ol>
+</nav>

package/dist/components/Steps.svelte.d.ts

@@ -0,0 +1,66 @@
+/** What .steps is made of, classified. The props follow the
+    families the project registers (variants.ts, ADR 0015). */
+export declare const PREFIX = "steps";
+export declare const AXES: {
+    readonly direction: readonly ["horizontal", "vertical"];
+    readonly color: readonly ["primary", "secondary", "accent", "neutral", "info", "success", "warning", "error"];
+    readonly size: readonly ["xs", "sm", "md", "lg", "xl"];
+};
+export declare const FLAGS: {
+    readonly compact: "No markers nor labels: the bars, and a heading above them (small screens).";
+};
+export declare const PARTS: readonly ["heading", "list", "item", "track", "marker", "segment", "label", "issue", "sublabel"];
+/** A stage of the journey. Its sub-steps go one level deep, no further. */
+export interface Step {
+    id: string | number;
+    label?: string;
+    /** The sub-steps. A step without any is a stage of its own. */
+    steps?: Step[];
+    /** Declared done by the app. Visiting a step does not complete it. */
+    complete?: boolean;
+    /** Shown once the step has been reached. */
+    error?: string;
+    warning?: string;
+}
+/** current · visited (reached before) · complete (declared) · unknown (not reached). */
+export type StepState = 'current' | 'visited' | 'complete' | 'unknown';
+/**
+     * Where the user is in a journey: one column per step, one bar per sub-step.
+     *
+     * The component moves nothing: a click calls `onStep` with the step, and
+     * the app decides whether to change `current`. A step is clickable once it
+     * has been reached (current, visited or complete) — a step's own marker
+     * leads to its first sub-step. `clickable={false}` or `disabled` turns that
+     * off.
+     *
+     * `explored` is the first leaf never reached; every leaf before it counts
+     * as visited. Without it, everything up to `current` does.
+     */
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import { type AxisProps } from '../variants.js';
+interface Props extends AxisProps<typeof AXES, typeof FLAGS, typeof PREFIX>, Omit<HTMLAttributes<HTMLElement>, 'color'> {
+    steps: Step[];
+    /** The id of the current leaf (a sub-step, or a step without any). */
+    current?: Step['id'];
+    /** The id of the first leaf never reached. */
+    explored?: Step['id'];
+    /** Reached steps answer clicks. */
+    clickable?: boolean;
+    disabled?: boolean;
+    /** A reached step was clicked: a leaf, or the first leaf of a step. */
+    onStep?: (step: Step) => void;
+    /** The line above the bars in compact mode. Defaults to "label · sub-label   n/total". */
+    heading?: Snippet<[{
+        step: Step | undefined;
+        parent: Step | undefined;
+        index: number;
+        total: number;
+    }]>;
+    /** The nav's accessible name. */
+    label?: string;
+    class?: string;
+}
+declare const Steps: import("svelte").Component<Props, {}, "">;
+type Steps = ReturnType<typeof Steps>;
+export default Steps;

package/dist/components/Subtitle.svelte

@@ -0,0 +1,44 @@
+<script module lang="ts">
+	/** What .subtitle is made of, classified. */
+	export const PREFIX = 'subtitle';
+
+	/* Two sizes, and they are the class suffix under a friendlier name: the
+	   map form of an axis exists for exactly this (see variants.ts). */
+	export const AXES = {
+		s: ['1', '2'],
+		color: ['primary', 'secondary', 'accent', 'neutral', 'info', 'success', 'warning', 'error']
+	} as const;
+
+	export const FLAGS = {} as const;
+	export const PARTS = [] as const;
+</script>
+
+<script lang="ts">
+	/**
+	 * A heading under the title.
+	 *
+	 * `s` is the look, `level` is the tag. They are independent on purpose —
+	 * see Title.svelte.
+	 */
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { applyAxes, cx, type AxisProps } from '../variants.js';
+
+	interface Props extends AxisProps<typeof AXES, typeof FLAGS, typeof PREFIX>, Omit<HTMLAttributes<HTMLHeadingElement>, 'color'> {
+		/** Which heading tag to render. Purely semantic; the look never moves. */
+		level?: 1 | 2 | 3 | 4 | 5 | 6;
+		class?: string;
+		children?: Snippet;
+	}
+
+	/* `s` is defaulted here rather than left out, because `.subtitle` alone is
+	   not a class — the size IS the base class. */
+	let { level = 2, s = '1', class: klass = '', children, ...axes }: Props = $props();
+
+	let applied = $derived(applyAxes(PREFIX, AXES, FLAGS, { ...axes, s }));
+	let classes = $derived(cx(applied.classes, klass));
+</script>
+
+<svelte:element this={`h${level}`} class={classes} {...applied.rest}>
+	{@render children?.()}
+</svelte:element>

package/dist/components/Subtitle.svelte.d.ts

@@ -0,0 +1,26 @@
+/** What .subtitle is made of, classified. */
+export declare const PREFIX = "subtitle";
+export declare const AXES: {
+    readonly s: readonly ["1", "2"];
+    readonly color: readonly ["primary", "secondary", "accent", "neutral", "info", "success", "warning", "error"];
+};
+export declare const FLAGS: {};
+export declare const PARTS: readonly [];
+/**
+     * A heading under the title.
+     *
+     * `s` is the look, `level` is the tag. They are independent on purpose —
+     * see Title.svelte.
+     */
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import { type AxisProps } from '../variants.js';
+interface Props extends AxisProps<typeof AXES, typeof FLAGS, typeof PREFIX>, Omit<HTMLAttributes<HTMLHeadingElement>, 'color'> {
+    /** Which heading tag to render. Purely semantic; the look never moves. */
+    level?: 1 | 2 | 3 | 4 | 5 | 6;
+    class?: string;
+    children?: Snippet;
+}
+declare const Subtitle: import("svelte").Component<Props, {}, "">;
+type Subtitle = ReturnType<typeof Subtitle>;
+export default Subtitle;

package/dist/components/Swatch.svelte

@@ -0,0 +1,61 @@
+<script module lang="ts">
+	/** What .swatch is made of, classified. The props follow the
+	    families the project registers (variants.ts, ADR 0015). */
+	export const PREFIX = 'swatch';
+
+	export const AXES = {
+		color: ['primary', 'secondary', 'accent', 'neutral', 'info', 'success', 'warning', 'error'],
+		size: ['xs', 'sm', 'md', 'lg', 'xl'],
+		shape: ['circle']
+	} as const;
+
+	export const FLAGS = {
+		active: 'Mark it as the chosen one.'
+	} as const;
+	export const PARTS = ['disabled'] as const;
+</script>
+
+<script lang="ts">
+	import type { Snippet } from 'svelte';
+	import type { HTMLAttributes } from 'svelte/elements';
+	import { applyAxes, cx, type AxisProps } from '../variants.js';
+
+	interface Props extends AxisProps<typeof AXES, typeof FLAGS, typeof PREFIX>, Omit<HTMLAttributes<HTMLSpanElement>, 'color'> {
+		/** The colour to show. It is DATA, not a theme value, so it is written
+		    here at the call site and never by the family. */
+		sample?: string;
+		/** Grey it out. `.swatch` may be a span, which cannot carry `disabled`. */
+		disabled?: boolean;
+		class?: string;
+		children?: Snippet;
+	}
+
+	// The axes are deliberately NOT destructured: they travel in `axes` and are
+	// resolved by name, so an axis a family drops changes nothing down here.
+	let {
+		sample,
+		disabled = false,
+		class: klass = '',
+		children,
+		...axes
+	}: Props = $props();
+
+	let applied = $derived(applyAxes(PREFIX, AXES, FLAGS, axes));
+	let classes = $derived(
+		cx(
+			PREFIX,
+			applied.classes,
+			disabled && `${PREFIX}-disabled`,
+			klass
+		)
+	);
+</script>
+
+<span
+	{...applied.rest}
+	class={classes}
+	style:--swatch-color={sample}
+	aria-disabled={disabled ? 'true' : undefined}
+>
+	{@render children?.()}
+</span>

package/dist/components/Swatch.svelte.d.ts

@@ -0,0 +1,27 @@
+/** What .swatch is made of, classified. The props follow the
+    families the project registers (variants.ts, ADR 0015). */
+export declare const PREFIX = "swatch";
+export declare const AXES: {
+    readonly color: readonly ["primary", "secondary", "accent", "neutral", "info", "success", "warning", "error"];
+    readonly size: readonly ["xs", "sm", "md", "lg", "xl"];
+    readonly shape: readonly ["circle"];
+};
+export declare const FLAGS: {
+    readonly active: "Mark it as the chosen one.";
+};
+export declare const PARTS: readonly ["disabled"];
+import type { Snippet } from 'svelte';
+import type { HTMLAttributes } from 'svelte/elements';
+import { type AxisProps } from '../variants.js';
+interface Props extends AxisProps<typeof AXES, typeof FLAGS, typeof PREFIX>, Omit<HTMLAttributes<HTMLSpanElement>, 'color'> {
+    /** The colour to show. It is DATA, not a theme value, so it is written
+        here at the call site and never by the family. */
+    sample?: string;
+    /** Grey it out. `.swatch` may be a span, which cannot carry `disabled`. */
+    disabled?: boolean;
+    class?: string;
+    children?: Snippet;
+}
+declare const Swatch: import("svelte").Component<Props, {}, "">;
+type Swatch = ReturnType<typeof Swatch>;
+export default Swatch;