@pienter/ui 0.2.0

package/components/feedback/alert/Alert.astro

@@ -0,0 +1,52 @@
+---
+import './alert.css';
+import Icon from '../../display/icon/Icon.astro';
+import type { IconName } from '../../../icons/index.js';
+
+type Tone = 'brand' | 'success' | 'warning' | 'danger';
+
+interface Props {
+  tone?: Tone;
+  title?: string;
+  /** Override the tone's default icon with a shipped one. Use the `icon` slot for a custom <svg>. */
+  icon?: IconName;
+}
+
+const toneIconMap: Record<Tone, IconName> = {
+  brand: 'info',
+  success: 'circle-check',
+  warning: 'alert-triangle',
+  danger: 'circle-alert',
+};
+
+const { tone, title, icon, ...rest } = Astro.props;
+const resolvedIcon: IconName = icon ?? (tone ? toneIconMap[tone] : 'info');
+const hasIconSlot = Astro.slots.has('icon');
+
+// the icon slot wins over the `icon` name; flag the redundant combination in dev
+if (import.meta.env.DEV && icon && hasIconSlot) {
+  console.warn(
+    '[pienter-ui] Alert received both an `icon` name and an `icon` slot; the slot is used and `icon` is ignored.',
+  );
+}
+---
+
+<div class="pui-alert" data-tone={tone} role="alert" {...rest}>
+  <span class="pui-alert__icon">
+    {
+      hasIconSlot ? (
+        <Icon size="md">
+          <slot name="icon" />
+        </Icon>
+      ) : (
+        <Icon name={resolvedIcon} size="md" />
+      )
+    }
+  </span>
+  <div class="pui-alert__content">
+    {title && <p class="pui-alert__title">{title}</p>}
+    <div class="pui-alert__body">
+      <slot />
+    </div>
+  </div>
+</div>

package/components/feedback/alert/Alert.vue

@@ -0,0 +1,60 @@
+<template>
+    <div class="pui-alert" :data-tone="tone" role="alert">
+        <span class="pui-alert__icon">
+            <Icon v-if="$slots.icon" size="md"><slot name="icon" /></Icon>
+            <Icon v-else :name="resolvedIcon" size="md" />
+        </span>
+        <div class="pui-alert__content">
+            <p v-if="title" class="pui-alert__title">{{ title }}</p>
+            <div class="pui-alert__body">
+                <slot />
+            </div>
+        </div>
+    </div>
+</template>
+
+<script setup lang="ts">
+import { computed, useSlots } from 'vue';
+import Icon from '../../display/icon/Icon.vue';
+import type { IconName } from '../../../icons/index.js';
+
+type Tone = 'brand' | 'success' | 'warning' | 'danger';
+
+const toneIconMap: Record<Tone, IconName> = {
+    brand: 'info',
+    success: 'circle-check',
+    warning: 'alert-triangle',
+    danger: 'circle-alert',
+};
+
+const props = withDefaults(
+    defineProps<{
+        tone?: Tone;
+        title?: string;
+        /** Override the tone's default icon with a shipped one. Use the `icon` slot for a custom <svg>. */
+        icon?: IconName;
+    }>(),
+    {
+        tone: undefined,
+        title: undefined,
+        icon: undefined,
+    },
+);
+
+const slots = useSlots();
+
+// the icon slot wins over the `icon` name; flag the redundant combination in dev
+if (props.icon && slots.icon) {
+    console.warn(
+        '[pienter-ui] Alert received both an `icon` name and an `icon` slot; the slot is used and `icon` is ignored.',
+    );
+}
+
+const resolvedIcon = computed<IconName>(
+    () => props.icon ?? (props.tone ? toneIconMap[props.tone] : 'info'),
+);
+</script>
+
+<style>
+@import './alert.css';
+</style>

package/components/feedback/alert/alert.css

@@ -0,0 +1,78 @@
+@layer components {
+    .pui-alert {
+        display: grid;
+        grid-template-columns: auto 1fr;
+        gap: var(--space-xs);
+        padding: var(--space-xs) var(--space-s);
+        border-radius: var(--radius-sm);
+        border: var(--stroke-sm) solid var(--border-clr-base);
+        /* tone-coloured left rule carries the emphasis (a non-colour cue too) */
+        border-left: var(--stroke-lg) solid var(--border-clr-strong);
+        background: var(--bg-clr-surface-2);
+
+        .pui-alert__icon {
+            display: grid;
+            place-items: center;
+            color: var(--text-clr-muted);
+        }
+
+        .pui-alert__content {
+            display: grid;
+            gap: 2px;
+        }
+
+        .pui-alert__title {
+            margin: 0;
+            font-weight: var(--fw-bold);
+            font-size: var(--step--1);
+        }
+
+        .pui-alert__body {
+            margin: 0;
+            color: var(--text-clr-muted);
+            font-size: var(--step--1);
+        }
+
+        /* ===== tones ===== */
+
+        &[data-tone='brand'] {
+            background: var(--bg-clr-brand-soft);
+            border-color: var(--border-clr-base);
+            border-left-color: var(--border-clr-brand);
+
+            .pui-alert__icon {
+                color: var(--text-clr-brand);
+            }
+        }
+
+        &[data-tone='success'] {
+            background: var(--bg-clr-success-soft);
+            border-color: var(--border-clr-base);
+            border-left-color: var(--border-clr-success);
+
+            .pui-alert__icon {
+                color: var(--text-clr-success);
+            }
+        }
+
+        &[data-tone='warning'] {
+            background: var(--bg-clr-warning-soft);
+            border-color: var(--border-clr-base);
+            border-left-color: var(--border-clr-warning);
+
+            .pui-alert__icon {
+                color: var(--text-clr-warning);
+            }
+        }
+
+        &[data-tone='danger'] {
+            background: var(--bg-clr-danger-soft);
+            border-color: var(--border-clr-base);
+            border-left-color: var(--border-clr-danger);
+
+            .pui-alert__icon {
+                color: var(--text-clr-danger);
+            }
+        }
+    }
+}

package/components/feedback/progress/Progress.astro

@@ -0,0 +1,68 @@
+---
+import './progress.css';
+
+interface Props {
+  /**
+   * Current value of the progress bar. When `null` or `undefined`, the
+   * component renders the indeterminate ("loading") state per WAI-ARIA
+   * convention — `aria-valuenow` is OMITTED from the wrapper so assistive
+   * technology announces an indeterminate progressbar.
+   */
+  value?: number | null;
+  /** Maximum value of the range. */
+  max?: number;
+  /** Minimum value of the range. */
+  min?: number;
+  /**
+   * Accessible name for the progressbar — emitted as `aria-label`. Omit
+   * when an external `aria-labelledby` is supplied via `...rest`.
+   */
+  label?: string;
+  /** Tone variant — drives indicator color via `data-tone`. */
+  tone?: 'brand' | 'success' | 'warning' | 'danger';
+}
+
+const {
+  value = null,
+  max = 100,
+  min = 0,
+  label,
+  tone = 'brand',
+  ...rest
+} = Astro.props;
+
+const isIndeterminate = value === null || value === undefined;
+
+const clampedValue = isIndeterminate
+  ? min
+  : Math.min(Math.max(value as number, min), max);
+
+const span = max - min;
+const percent =
+  isIndeterminate || span <= 0 ? 0 : ((clampedValue - min) / span) * 100;
+
+const state: 'loading' | 'in-progress' | 'complete' = isIndeterminate
+  ? 'loading'
+  : clampedValue === max
+    ? 'complete'
+    : 'in-progress';
+
+const indicatorStyle: Record<string, string> = {};
+if (!isIndeterminate) {
+  indicatorStyle.width = `${percent}%`;
+}
+---
+
+<div
+  class="pui-progress"
+  role="progressbar"
+  aria-valuenow={isIndeterminate ? undefined : clampedValue}
+  aria-valuemin={min}
+  aria-valuemax={max}
+  aria-label={label}
+  data-state={state}
+  data-tone={tone}
+  {...rest}
+>
+  <div class="pui-progress__indicator" style={indicatorStyle}></div>
+</div>

package/components/feedback/progress/Progress.vue

@@ -0,0 +1,82 @@
+<template>
+    <div
+        class="pui-progress"
+        role="progressbar"
+        :aria-valuenow="isIndeterminate ? undefined : clampedValue"
+        :aria-valuemin="min"
+        :aria-valuemax="max"
+        :aria-label="label"
+        :data-state="state"
+        :data-tone="tone"
+    >
+        <div class="pui-progress__indicator" :style="indicatorStyle" />
+    </div>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+
+const props = withDefaults(
+    defineProps<{
+        /**
+         * Current value of the progress bar. When `null` or `undefined`, the
+         * component renders the indeterminate ("loading") state per WAI-ARIA
+         * convention — `aria-valuenow` is OMITTED from the wrapper so assistive
+         * technology announces an indeterminate progressbar.
+         */
+        value?: number | null;
+        /** Maximum value of the range. */
+        max?: number;
+        /** Minimum value of the range. */
+        min?: number;
+        /**
+         * Accessible name for the progressbar — emitted as `aria-label`. Omit
+         * when an external `aria-labelledby` is supplied via `$attrs`.
+         */
+        label?: string;
+        /** Tone variant — drives indicator color via `data-tone`. */
+        tone?: 'brand' | 'success' | 'warning' | 'danger';
+    }>(),
+    {
+        value: null,
+        max: 100,
+        min: 0,
+        label: undefined,
+        tone: 'brand',
+    },
+);
+
+const isIndeterminate = computed(
+    () => props.value === null || props.value === undefined,
+);
+
+const clampedValue = computed(() => {
+    if (isIndeterminate.value) return props.min;
+    const v = props.value as number;
+    if (v < props.min) return props.min;
+    if (v > props.max) return props.max;
+    return v;
+});
+
+const percent = computed(() => {
+    if (isIndeterminate.value) return 0;
+    const span = props.max - props.min;
+    if (span <= 0) return 0;
+    return ((clampedValue.value - props.min) / span) * 100;
+});
+
+const state = computed<'loading' | 'in-progress' | 'complete'>(() => {
+    if (isIndeterminate.value) return 'loading';
+    if (clampedValue.value === props.max) return 'complete';
+    return 'in-progress';
+});
+
+const indicatorStyle = computed(() => {
+    if (isIndeterminate.value) return {};
+    return { width: `${percent.value}%` };
+});
+</script>
+
+<style>
+@import './progress.css';
+</style>

package/components/feedback/progress/progress.css

@@ -0,0 +1,68 @@
+@layer components {
+    .pui-progress {
+        display: block;
+        width: 100%;
+        height: 0.5rem;
+        background-color: var(--bg-clr-surface-2);
+        border-radius: var(--radius-pill);
+        overflow: hidden;
+        /* Establish containing block for the indeterminate animation so the
+     * indicator's transform is clipped to the track. */
+        position: relative;
+    }
+
+    .pui-progress__indicator {
+        display: block;
+        height: 100%;
+        width: 0%;
+        background-color: var(--bg-clr-brand);
+        border-radius: inherit;
+        /* Smooth width transition for determinate updates. */
+        transition: width 200ms ease-out;
+    }
+
+    /* Tone variants — color the indicator. */
+    .pui-progress[data-tone='success'] .pui-progress__indicator {
+        background-color: var(--bg-clr-success);
+    }
+
+    .pui-progress[data-tone='warning'] .pui-progress__indicator {
+        background-color: var(--bg-clr-warning);
+    }
+
+    .pui-progress[data-tone='danger'] .pui-progress__indicator {
+        background-color: var(--bg-clr-danger);
+    }
+
+    /* Indeterminate (loading) state — no determinate `aria-valuenow`. The
+   * indicator becomes a moving bar that scrolls across the track. */
+    .pui-progress[data-state='loading'] .pui-progress__indicator {
+        width: 40%;
+        /* Drop the determinate width transition; animation owns motion. */
+        transition: none;
+        animation: pui-progress-indeterminate 1.4s ease-in-out infinite;
+    }
+
+    @keyframes pui-progress-indeterminate {
+        0% {
+            transform: translateX(-100%);
+        }
+        100% {
+            transform: translateX(250%);
+        }
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+        .pui-progress__indicator {
+            transition: none;
+        }
+
+        .pui-progress[data-state='loading'] .pui-progress__indicator {
+            /* Replace the moving-bar shimmer with a static, full-width fill
+       * so the loading state remains visible without motion. */
+            animation: none;
+            width: 100%;
+            opacity: 0.55;
+        }
+    }
+}

package/components/feedback/skeleton/Skeleton.astro

@@ -0,0 +1,32 @@
+---
+import './skeleton.css';
+
+interface Props {
+  variant?: 'text' | 'rect' | 'circle';
+  width?: string;
+  height?: string;
+  rounded?: boolean;
+}
+
+const {
+  variant = 'rect',
+  width,
+  height,
+  rounded = false,
+  ...rest
+} = Astro.props;
+
+const inlineStyle: Record<string, string> = {};
+if (width) inlineStyle.width = width;
+if (height) inlineStyle.height = height;
+---
+
+<div
+  class="pui-skeleton"
+  data-variant={variant}
+  data-rounded={rounded ? '' : undefined}
+  style={inlineStyle}
+  aria-hidden="true"
+  {...rest}
+>
+</div>

package/components/feedback/skeleton/Skeleton.vue

@@ -0,0 +1,39 @@
+<template>
+    <div
+        class="pui-skeleton"
+        :data-variant="variant"
+        :data-rounded="rounded ? '' : null"
+        :style="inlineStyle"
+        aria-hidden="true"
+    />
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+
+const props = withDefaults(
+    defineProps<{
+        variant?: 'text' | 'rect' | 'circle';
+        width?: string;
+        height?: string;
+        rounded?: boolean;
+    }>(),
+    {
+        variant: 'rect',
+        width: undefined,
+        height: undefined,
+        rounded: false,
+    },
+);
+
+const inlineStyle = computed(() => {
+    const style: Record<string, string> = {};
+    if (props.width) style.width = props.width;
+    if (props.height) style.height = props.height;
+    return style;
+});
+</script>
+
+<style>
+@import './skeleton.css';
+</style>

package/components/feedback/skeleton/skeleton.css

@@ -0,0 +1,56 @@
+@layer components {
+    .pui-skeleton {
+        display: block;
+        background-color: var(--bg-clr-surface-2);
+        background-image: linear-gradient(
+            90deg,
+            transparent 0%,
+            hsl(from var(--bg-clr-base) h s l / 0.55) 50%,
+            transparent 100%
+        );
+        background-size: 200% 100%;
+        background-repeat: no-repeat;
+        background-position: -150% 0;
+        animation: pui-skeleton-shimmer 1.4s ease-in-out infinite;
+        border-radius: var(--radius-sm);
+    }
+
+    .pui-skeleton[data-variant='rect'] {
+        width: 100%;
+        height: 8rem;
+    }
+
+    .pui-skeleton[data-variant='rect'][data-rounded] {
+        border-radius: var(--radius-md);
+    }
+
+    .pui-skeleton[data-variant='text'] {
+        display: inline-block;
+        width: 100%;
+        height: 1em;
+        border-radius: var(--radius-xs);
+        vertical-align: middle;
+    }
+
+    .pui-skeleton[data-variant='circle'] {
+        width: 2.4rem;
+        height: 2.4rem;
+        border-radius: 50%;
+    }
+
+    @keyframes pui-skeleton-shimmer {
+        0% {
+            background-position: -150% 0;
+        }
+        100% {
+            background-position: 250% 0;
+        }
+    }
+
+    @media (prefers-reduced-motion: reduce) {
+        .pui-skeleton {
+            animation: none;
+            background-image: none;
+        }
+    }
+}

package/components/feedback/spinner/Spinner.astro

@@ -0,0 +1,25 @@
+---
+// Spinner (Astro) — same contract as Spinner.vue; composes Icon so the spin stays in icon.css.
+import './spinner.css';
+import Icon from '../../display/icon/Icon.astro';
+
+interface Props {
+  size?: 'sm' | 'md' | 'lg' | 'xl';
+  /** Accessible name; supply it when the spinner is the only signal. See Spinner.vue. */
+  label?: string;
+}
+
+const { size = 'md', label, ...rest } = Astro.props;
+---
+
+<span
+  class="pui-spinner"
+  data-size={size}
+  role={label ? 'status' : undefined}
+  aria-hidden={label ? undefined : 'true'}
+  {...rest}
+>
+  <Icon name="loader" animation="spin" />
+  {/* Real text, not an aria-label — see Spinner.vue. */}
+  {label && <span class="pui-spinner__label">{label}</span>}
+</span>

package/components/feedback/spinner/Spinner.vue

@@ -0,0 +1,36 @@
+<!--
+    Spinner — the indeterminate "working" indicator. Composes Icon, so the glyph, the spin
+    and the reduced-motion escape stay defined once in icon.css; adds a larger size scale.
+-->
+<template>
+    <span
+        class="pui-spinner"
+        :data-size="size"
+        :role="label ? 'status' : undefined"
+        :aria-hidden="label ? undefined : true"
+    >
+        <Icon name="loader" animation="spin" />
+        <!-- Real text, not an `aria-label`: a live region whose only child is `aria-hidden` announces nothing. -->
+        <span v-if="label" class="pui-spinner__label">{{ label }}</span>
+    </span>
+</template>
+
+<script setup lang="ts">
+import Icon from '../../display/icon/Icon.vue';
+
+withDefaults(
+    defineProps<{
+        size?: 'sm' | 'md' | 'lg' | 'xl';
+        /**
+         * Accessible name, making the spinner a `role="status"` region. Omit it when
+         * something around it already carries the state (`aria-busy`, a "Saving…" label).
+         */
+        label?: string;
+    }>(),
+    { size: 'md', label: undefined },
+);
+</script>
+
+<style>
+@import './spinner.css';
+</style>

package/components/feedback/spinner/spinner.css

@@ -0,0 +1,91 @@
+@layer components {
+    .pui-spinner {
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        flex-shrink: 0;
+        line-height: 1;
+
+        /* ===== sizes ===== */
+
+        /* Own scale because Spinner outgrows Icon's (which stops at lg); set per size
+           because the rule reading the property is itself [data-size]-qualified. */
+
+        &[data-size='sm'] {
+            --pui-spinner-size: 1rem;
+        }
+
+        &[data-size='md'] {
+            --pui-spinner-size: 1.5rem;
+        }
+
+        &[data-size='lg'] {
+            --pui-spinner-size: 2rem;
+        }
+
+        &[data-size='xl'] {
+            --pui-spinner-size: 2.75rem;
+        }
+
+        /* [data-size]-qualified to outrank icon.css's `[data-size] svg` in the same layer. */
+        &[data-size] .pui-icon svg {
+            width: var(--pui-spinner-size, 1.5rem);
+            height: var(--pui-spinner-size, 1.5rem);
+        }
+
+        /* Live-region text: in the DOM and out of sight, so the region has content to
+           announce. Inlined rather than borrowed from the utilities layer. */
+        & .pui-spinner__label {
+            position: absolute;
+            width: 1px;
+            height: 1px;
+            overflow: hidden;
+            clip-path: inset(50%);
+            white-space: nowrap;
+        }
+
+        /* ===== motion ===== */
+
+        /* One step per spoke (360deg / 8): each tick lands a spoke where its neighbour was,
+           so the ramp appears to advance one position. [data-size]-qualified as above. */
+        &[data-size] .pui-icon {
+            animation-timing-function: steps(8);
+        }
+
+        /* ===== the chasing tail ===== */
+
+        /* Coupled to the rotation: the wrapper spins clockwise, so brightness must increase
+           clockwise over `loader`'s clockwise spokes, or the tail leads — see AUDIT.md. */
+        & svg path:nth-child(1) {
+            opacity: 0.13;
+        }
+
+        & svg path:nth-child(2) {
+            opacity: 0.22;
+        }
+
+        & svg path:nth-child(3) {
+            opacity: 0.33;
+        }
+
+        & svg path:nth-child(4) {
+            opacity: 0.45;
+        }
+
+        & svg path:nth-child(5) {
+            opacity: 0.58;
+        }
+
+        & svg path:nth-child(6) {
+            opacity: 0.72;
+        }
+
+        & svg path:nth-child(7) {
+            opacity: 0.86;
+        }
+
+        & svg path:nth-child(8) {
+            opacity: 1;
+        }
+    }
+}