@pienter/ui 0.2.0

package/components/form/input-otp/InputOTP.astro

@@ -0,0 +1,147 @@
+---
+import './input-otp.css';
+import { generateId } from '../../../utils/a11y/id.js';
+
+interface Props {
+  id?: string;
+  label: string;
+  name?: string;
+  /**
+   * Initial OTP string. Length matches `length` (Astro pads with empty
+   * characters or trims as needed before rendering slots).
+   */
+  value?: string;
+  /** Number of slots (default 6). */
+  length?: number;
+  /**
+   * Per-character validation pattern as a string (regex source). Default
+   * is digits-only `^[0-9]$`. Pass an alphanumeric pattern as a regex
+   * source string when the OTP code includes letters. The string is
+   * stored on a `data-pattern` attribute so the controller can rehydrate
+   * the regex post-mount.
+   */
+  pattern?: string;
+  disabled?: boolean;
+  hint?: string;
+  errors?: string[];
+  status?: 'error' | 'success';
+}
+
+const {
+  id,
+  label,
+  name,
+  value = '',
+  length = 6,
+  pattern,
+  disabled = false,
+  hint,
+  errors = [],
+  status,
+  ...rest
+} = Astro.props;
+
+const firstSlotId = id ?? generateId('input');
+const hintId = `${firstSlotId}-hint`;
+const errorsId = `${firstSlotId}-errors`;
+
+const hasErrors = errors.length > 0;
+const computedStatus = status ?? (hasErrors ? 'error' : undefined);
+
+const describedByIds: string[] = [];
+if (hint) describedByIds.push(hintId);
+if (hasErrors) describedByIds.push(errorsId);
+const describedBy =
+  describedByIds.length > 0 ? describedByIds.join(' ') : undefined;
+
+// Pad / trim seed value to the slot count.
+const slots = Array.from({ length }, (_, i) => value[i] ?? '');
+---
+
+<div class="pui-field" data-status={computedStatus}>
+  <label class="pui-field__label" for={firstSlotId}>
+    {label}
+  </label>
+  <div
+    class="pui-input-otp"
+    data-pui-input-otp
+    data-disabled={disabled ? 'true' : undefined}
+    data-pattern={pattern}
+    role="group"
+  >
+    {
+      slots.map((char, i) => (
+        <input
+          class="pui-input-otp__slot pui-input"
+          type="text"
+          inputmode="numeric"
+          autocomplete="one-time-code"
+          maxlength="1"
+          id={i === 0 ? firstSlotId : `${firstSlotId}-slot-${i + 1}`}
+          aria-label={`Digit ${i + 1} of ${length}`}
+          value={char}
+          disabled={disabled}
+          aria-invalid={i === 0 && hasErrors ? 'true' : undefined}
+          aria-describedby={i === 0 ? describedBy : undefined}
+          {...(i === 0 ? rest : {})}
+        />
+      ))
+    }
+    {
+      name && (
+        <input
+          class="pui-input-otp__hidden"
+          type="hidden"
+          name={name}
+          value={value}
+        />
+      )
+    }
+  </div>
+  {
+    hint && (
+      <p id={hintId} class="pui-field__hint">
+        {hint}
+      </p>
+    )
+  }
+  {
+    hasErrors && (
+      <ul id={errorsId} class="pui-field__hint" role="alert">
+        {errors.map((error) => (
+          <li>{error}</li>
+        ))}
+      </ul>
+    )
+  }
+</div>
+
+<script>
+  import { mountInputOTP } from '@pienter/ui/utils/controllers/otp.js';
+
+  // Hoisted module script — Astro de-dupes across instances.
+  function mountAll(): void {
+    const wrappers = document.querySelectorAll<HTMLElement>(
+      '[data-pui-input-otp]',
+    );
+    wrappers.forEach((wrapper) => {
+      if (wrapper.dataset.vInputOtpMounted === 'true') return;
+      let pattern: RegExp | undefined;
+      if (wrapper.dataset.pattern) {
+        try {
+          pattern = new RegExp(wrapper.dataset.pattern);
+        } catch {
+          pattern = undefined;
+        }
+      }
+      mountInputOTP(wrapper, { pattern });
+      wrapper.dataset.vInputOtpMounted = 'true';
+    });
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', mountAll, { once: true });
+  } else {
+    mountAll();
+  }
+</script>

package/components/form/input-otp/InputOTP.vue

@@ -0,0 +1,209 @@
+<template>
+    <div class="pui-field" :data-status="computedStatus">
+        <label class="pui-field__label" :for="firstSlotId">{{ label }}</label>
+        <div
+            class="pui-input-otp"
+            :data-disabled="disabled ? 'true' : undefined"
+            role="group"
+            :aria-labelledby="undefined"
+        >
+            <input
+                v-for="i in length"
+                :id="i === 1 ? firstSlotId : `${firstSlotId}-slot-${i}`"
+                :key="i"
+                :ref="(el) => setSlotRef(el, i - 1)"
+                class="pui-input-otp__slot pui-input"
+                type="text"
+                inputmode="numeric"
+                autocomplete="one-time-code"
+                maxlength="1"
+                :aria-label="`Digit ${i} of ${length}`"
+                :value="slotChar(i - 1)"
+                :disabled="disabled"
+                :aria-invalid="hasErrors ? 'true' : undefined"
+                :aria-describedby="i === 1 ? describedBy : undefined"
+                @input="(e) => onSlotInput(e, i - 1)"
+                @keydown="(e) => onSlotKeydown(e, i - 1)"
+                @paste="(e) => onSlotPaste(e, i - 1)"
+                @focus="(e) => onSlotFocus(e)"
+            />
+            <input v-if="name" type="hidden" :name="name" :value="modelValue" />
+        </div>
+        <p v-if="hint" :id="hintId" class="pui-field__hint">{{ hint }}</p>
+        <ul
+            v-if="errors.length"
+            :id="errorsId"
+            class="pui-field__hint"
+            role="alert"
+        >
+            <li v-for="error in errors" :key="error">{{ error }}</li>
+        </ul>
+    </div>
+</template>
+
+<script setup lang="ts">
+import { computed, ref, type ComponentPublicInstance } from 'vue';
+import { generateId } from '../../../utils/a11y/id.js';
+
+defineOptions({ inheritAttrs: false });
+
+const props = withDefaults(
+    defineProps<{
+        id?: string;
+        label: string;
+        /** Concatenated OTP string. Length always matches `length`; unfilled slots are empty characters. */
+        modelValue: string;
+        name?: string;
+        /** Number of slots (default 6). */
+        length?: number;
+        /**
+         * Per-character validation pattern. Default digits-only
+         * (`/^[0-9]$/`). Pass an alphanumeric pattern for OTP codes that
+         * include letters.
+         */
+        pattern?: RegExp;
+        disabled?: boolean;
+        hint?: string;
+        errors?: string[];
+        status?: 'error' | 'success';
+    }>(),
+    {
+        id: undefined,
+        name: undefined,
+        length: 6,
+        pattern: () => /^[0-9]$/,
+        disabled: false,
+        hint: undefined,
+        errors: () => [],
+        status: undefined,
+    },
+);
+
+const emit = defineEmits<{
+    'update:modelValue': [value: string];
+}>();
+
+const slotRefs = ref<HTMLInputElement[]>([]);
+
+function setSlotRef(
+    el: Element | ComponentPublicInstance | null,
+    index: number,
+): void {
+    if (el instanceof HTMLInputElement) {
+        slotRefs.value[index] = el;
+    }
+}
+
+const firstSlotId = props.id ?? generateId('input');
+const hintId = `${firstSlotId}-hint`;
+const errorsId = `${firstSlotId}-errors`;
+
+const hasErrors = computed(() => props.errors.length > 0);
+
+const computedStatus = computed(() => {
+    if (props.status) return props.status;
+    if (hasErrors.value) return 'error';
+    return undefined;
+});
+
+const describedBy = computed(() => {
+    const ids: string[] = [];
+    if (props.hint) ids.push(hintId);
+    if (hasErrors.value) ids.push(errorsId);
+    return ids.length > 0 ? ids.join(' ') : undefined;
+});
+
+function slotChar(idx: number): string {
+    return props.modelValue[idx] ?? '';
+}
+
+function setChar(idx: number, ch: string): void {
+    const arr = Array.from({ length: props.length }, (_, i) => slotChar(i));
+    arr[idx] = ch;
+    emit('update:modelValue', arr.join(''));
+}
+
+function focusSlot(idx: number): void {
+    const target = slotRefs.value[idx];
+    if (target) {
+        target.focus();
+        target.select();
+    }
+}
+
+function onSlotInput(event: Event, idx: number): void {
+    const target = event.target as HTMLInputElement;
+    const raw = target.value;
+    if (raw.length === 0) {
+        setChar(idx, '');
+        return;
+    }
+    // Multi-char input (paste fallback): take last char, validate.
+    const ch = raw.length > 1 ? (raw[raw.length - 1] ?? '') : raw;
+    if (!props.pattern.test(ch)) {
+        target.value = slotChar(idx); // restore previous
+        return;
+    }
+    target.value = ch;
+    setChar(idx, ch);
+    if (idx < props.length - 1) {
+        focusSlot(idx + 1);
+    }
+}
+
+function onSlotKeydown(event: KeyboardEvent, idx: number): void {
+    const target = event.target as HTMLInputElement;
+
+    if (event.key === 'Backspace') {
+        if (target.value.length === 0 && idx > 0) {
+            event.preventDefault();
+            setChar(idx - 1, '');
+            focusSlot(idx - 1);
+        } else if (target.value.length > 0) {
+            event.preventDefault();
+            setChar(idx, '');
+        }
+        return;
+    }
+
+    if (event.key === 'ArrowLeft' && idx > 0) {
+        event.preventDefault();
+        focusSlot(idx - 1);
+        return;
+    }
+
+    if (event.key === 'ArrowRight' && idx < props.length - 1) {
+        event.preventDefault();
+        focusSlot(idx + 1);
+        return;
+    }
+}
+
+function onSlotPaste(event: ClipboardEvent, idx: number): void {
+    const data = event.clipboardData?.getData('text') ?? '';
+    if (!data) return;
+    event.preventDefault();
+    const valid = Array.from(data).filter((ch) => props.pattern.test(ch));
+    if (valid.length === 0) return;
+    const arr = Array.from({ length: props.length }, (_, i) => slotChar(i));
+    let cursor = idx;
+    for (const ch of valid) {
+        if (cursor >= props.length) break;
+        arr[cursor] = ch;
+        cursor += 1;
+    }
+    emit('update:modelValue', arr.join(''));
+    const landingIdx = Math.min(cursor, props.length - 1);
+    focusSlot(landingIdx);
+}
+
+function onSlotFocus(event: FocusEvent): void {
+    if (event.target instanceof HTMLInputElement) {
+        event.target.select();
+    }
+}
+</script>
+
+<style>
+@import './input-otp.css';
+</style>

package/components/form/input-otp/input-otp.css

@@ -0,0 +1,52 @@
+@layer components {
+    /* ===== pui-input-otp (row of N single-character inputs) =====
+   *
+   * InputOTP extends the locked Form-primitive scaffold with an
+   * inline-flex row of N native `<input maxlength="1">` slots. Each
+   * slot inherits the shared `.pui-input` rule (sizing / padding /
+   * focus-ring / status recolour) for visual parity with TextInput
+   * and NumberField; the per-component overrides here narrow the
+   * width to a square box and centre the typed character so the
+   * code reads as one unit.
+   *
+   * Layout rationale: rejected the "single underline-bordered row"
+   * alternative because per-slot rectangles match shadcn / Reka
+   * conventions and make focus more legible (each slot's
+   * `:focus-visible` ring is independently obvious to keyboard
+   * users).
+   */
+
+    .pui-input-otp {
+        display: inline-flex;
+        align-items: center;
+        gap: var(--space-2xs);
+    }
+
+    .pui-input-otp[data-disabled='true'] {
+        opacity: 0.7;
+    }
+
+    .pui-input-otp__slot {
+        /* Inherits sizing, padding, focus-ring, disabled, and status
+     * recolour from the shared .pui-input rule (text-input.css). The
+     * overrides here narrow the slot to a square box and centre the
+     * typed character. */
+        width: 2.75rem;
+        text-align: center;
+        padding-inline: 0;
+        font-variant-numeric: tabular-nums;
+        font-size: var(--step-1, 1.125rem);
+        /* Slightly tighter min-height so a 6-slot row fits common form widths. */
+        line-height: 1.2;
+    }
+
+    /* Status states inherited from .pui-field — recolour every slot when
+   * the parent carries `data-status`. */
+    .pui-field[data-status='error'] .pui-input-otp__slot {
+        border-color: var(--border-clr-danger);
+    }
+
+    .pui-field[data-status='success'] .pui-input-otp__slot {
+        border-color: var(--border-clr-success);
+    }
+}

package/components/form/label/Label.astro

@@ -0,0 +1,13 @@
+---
+import './label.css';
+
+interface Props {
+  for?: string;
+}
+
+const { for: htmlFor, ...rest } = Astro.props;
+---
+
+<label class="pui-field__label" for={htmlFor} {...rest}>
+  <slot />
+</label>

package/components/form/label/Label.vue

@@ -0,0 +1,20 @@
+<template>
+    <label class="pui-field__label" :for="props.for">
+        <slot />
+    </label>
+</template>
+
+<script setup lang="ts">
+const props = withDefaults(
+    defineProps<{
+        for?: string;
+    }>(),
+    {
+        for: undefined,
+    },
+);
+</script>
+
+<style>
+@import './label.css';
+</style>

package/components/form/label/label.css

@@ -0,0 +1,11 @@
+/*
+ * Label is a near-empty stylesheet. The actual `.pui-field__label` rules
+ * live in `components/form/text-input/text-input.css` (the shared form-primitive
+ * scaffold). Label exposes the same class as a standalone component for
+ * use cases where the form-primitive components' built-in label is not
+ * suitable (e.g., labels associated with custom groups or with multiple
+ * controls). Importing this file re-imports the scaffold so a
+ * standalone Label dragged into an Astro page that does not also use
+ * TextInput / Textarea / Select still gets the typography rules.
+ */
+@import '../text-input/text-input.css';

package/components/form/number-field/NumberField.astro

@@ -0,0 +1,142 @@
+---
+import './number-field.css';
+import { generateId } from '../../../utils/a11y/id.js';
+
+interface Props {
+  id?: string;
+  label: string;
+  name?: string;
+  /**
+   * Initial numeric value. Astro renders the value once at SSR time;
+   * dynamic updates are handled by the consumer's own scripts (see
+   * the consumer-wires-their-own-script pattern in CONVENTIONS) or
+   * by the increment/decrement buttons via `mountNumberField`.
+   */
+  value?: number | string;
+  min?: number;
+  max?: number;
+  step?: number | string;
+  placeholder?: string;
+  required?: boolean;
+  disabled?: boolean;
+  hint?: string;
+  errors?: string[];
+  status?: 'error' | 'success';
+}
+
+const {
+  id,
+  label,
+  name,
+  value,
+  min,
+  max,
+  step,
+  placeholder,
+  required = false,
+  disabled = false,
+  hint,
+  errors = [],
+  status,
+  ...rest
+} = Astro.props;
+
+const inputId = id ?? generateId('input');
+const hintId = `${inputId}-hint`;
+const errorsId = `${inputId}-errors`;
+
+const hasErrors = errors.length > 0;
+const computedStatus = status ?? (hasErrors ? 'error' : undefined);
+
+const describedByIds: string[] = [];
+if (hint) describedByIds.push(hintId);
+if (hasErrors) describedByIds.push(errorsId);
+const describedBy =
+  describedByIds.length > 0 ? describedByIds.join(' ') : undefined;
+---
+
+<div class="pui-field" data-status={computedStatus}>
+  <label class="pui-field__label" for={inputId}>
+    {label}
+  </label>
+  <div class="pui-number-field" data-pui-number-field>
+    <input
+      class="pui-number-field__input pui-input"
+      type="number"
+      id={inputId}
+      name={name}
+      min={min}
+      max={max}
+      step={step}
+      placeholder={placeholder}
+      required={required}
+      disabled={disabled}
+      value={value}
+      aria-invalid={hasErrors ? 'true' : undefined}
+      aria-describedby={describedBy}
+      {...rest}
+    />
+    <div class="pui-number-field__steppers">
+      <button
+        type="button"
+        class="pui-number-field__step"
+        data-direction="increment"
+        aria-label="Increase"
+        disabled={disabled}
+      >
+        <span aria-hidden="true">+</span>
+      </button>
+      <button
+        type="button"
+        class="pui-number-field__step"
+        data-direction="decrement"
+        aria-label="Decrease"
+        disabled={disabled}
+      >
+        <span aria-hidden="true">&#x2212;</span>
+      </button>
+    </div>
+  </div>
+  {
+    hint && (
+      <p id={hintId} class="pui-field__hint">
+        {hint}
+      </p>
+    )
+  }
+  {
+    hasErrors && (
+      <ul id={errorsId} class="pui-field__hint" role="alert">
+        {errors.map((error) => (
+          <li>{error}</li>
+        ))}
+      </ul>
+    )
+  }
+</div>
+
+<script>
+  import { mountNumberField } from '@pienter/ui/utils/controllers/number-field.js';
+
+  // Hoisted module script — Astro de-dupes this across every NumberField
+  // instance on the page. Mount the controller on each [data-pui-number-field]
+  // wrapper present at DOM-ready. See CONVENTIONS § hoisted-vs-inline rule.
+  function mountAll(): void {
+    const wrappers = document.querySelectorAll<HTMLElement>(
+      '[data-pui-number-field]',
+    );
+    wrappers.forEach((wrapper) => {
+      // Idempotency guard: skip wrappers that have already been mounted
+      // (e.g. on Astro view transitions / partial re-renders).
+      if (wrapper.dataset.vNumberFieldMounted === 'true') return;
+      mountNumberField(wrapper);
+      wrapper.dataset.vNumberFieldMounted = 'true';
+    });
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', mountAll, { once: true });
+  } else {
+    mountAll();
+  }
+</script>