@cahyo-dimas/freeday 3.10.0 → 3.12.0

package/adapters/vue/components/FdyTimepicker.vue

@@ -0,0 +1,285 @@
+<script setup lang="ts">
+import { computed, nextTick, onBeforeUnmount, onMounted, ref, useId, type ComputedRef, type Ref } from 'vue';
+import { usePopover } from '../usePopover';
+
+// A Vue-native binding over freeday's `.fdy-timepicker` classes (src/components/timepicker.css).
+// The kit also ships a framework-agnostic enhancer (freeday-timepicker.js), but letting it own the
+// DOM would fight Vue's rendering and leave no `v-model` — the same reason FdyCombo re-implements
+// the listbox rather than wrapping freeday-select.js. Charts delegate to their renderer; form
+// controls do not.
+//
+// `<input type="time">` is what this replaces, and the reason is not theming alone: the native
+// picker is drawn by the OPERATING SYSTEM, so iOS shows a scroll wheel, Android a clock dial and
+// desktop a stepper, each with its own width and value format, and no CSS reaches any of them. A
+// phone and a browser at the same width therefore disagree about a screen that is otherwise
+// identical. Raised from keamanan-cluster, whose shift form was audited on an iPhone 7 (#094).
+//
+// Deliberate difference from the enhancer: focus stays on the TRIGGER with `aria-activedescendant`
+// on it, which is what FdyCombo, FdyDatepicker and FdyAutocomplete do, rather than moving focus
+// into the panel as the raw path does. Both are valid APG listbox patterns; one family, one model.
+
+const props = defineProps<{
+  /** `HH:MM`, 24-hour. `''`/`null` for empty. A loose `H:MM` is normalised for matching. */
+  modelValue: string | null;
+  /** Minutes between options. Default 30. */
+  step?: number;
+  /** `HH:MM` bounds, inclusive. Default `00:00` to `23:59`. */
+  min?: string;
+  max?: string;
+  id?: string;
+  ariaLabel?: string;
+  ariaLabelledby?: string;
+  /** Shown when there is no value. Default `--:--`, the same as the raw path. */
+  placeholder?: string;
+  disabled?: boolean;
+  /** Locked/view mode: stays focusable and shows its time, but can't be opened or changed. Unlike `disabled`, it keeps tab order and isn't greyed. */
+  readonly?: boolean;
+  /**
+   * Let a `data-fdy-validate` form demand this control be filled. It renders `data-fdy-required`
+   * on the root, and `freeday-form.js` refuses the submit, paints the message in the field and
+   * focuses the trigger. Needed because the trigger is a `<button>`: `willValidate` is false, so
+   * a plain `required` on it has never meant anything (#096). Override the message per control
+   * with `data-fdy-msg-required`, which falls through onto the root.
+   */
+  required?: boolean;
+  invalid?: boolean;
+  describedby?: string;
+}>();
+
+const emit = defineEmits<{
+  'update:modelValue': [value: string];
+  change: [value: string];
+}>();
+
+const SHAPE: RegExp = /^\d{1,2}:\d{2}$/;
+
+function toMinutes(time: string): number {
+  const [h, m] = time.split(':');
+  return Number(h) * 60 + Number(m);
+}
+function pad(n: number): string {
+  return n < 10 ? `0${n}` : String(n);
+}
+function fromMinutes(total: number): string {
+  return `${pad(Math.floor(total / 60))}:${pad(total % 60)}`;
+}
+/** `7:0` is not a time; `7:00` is the same time as `07:00`. Anything else answers `''`. */
+function normalise(time: string | null): string {
+  if (time === null || !SHAPE.test(time)) return '';
+  const total: number = toMinutes(time);
+  return total >= 0 && total <= 23 * 60 + 59 ? fromMinutes(total) : '';
+}
+function bound(time: string | undefined, fallback: number): number {
+  return time !== undefined && SHAPE.test(time) ? toMinutes(time) : fallback;
+}
+
+const baseId: string = useId();
+const triggerId: ComputedRef<string> = computed((): string => props.id ?? `${baseId}-trigger`);
+const panelId: string = `${baseId}-panel`;
+function optionId(index: number): string {
+  return `${baseId}-opt-${index}`;
+}
+
+const rootEl: Ref<HTMLDivElement | null> = ref(null);
+const triggerEl: Ref<HTMLButtonElement | null> = ref(null);
+const panelEl: Ref<HTMLUListElement | null> = ref(null);
+const open: Ref<boolean> = ref(false);
+
+// Lift the panel into the top layer so it escapes an ancestor overflow clip. A shift form is a
+// modal, and a time list long enough to scroll is exactly the panel a card would cut off.
+usePopover(panelEl, triggerEl, open);
+const highlighted: Ref<number> = ref(-1);
+
+const times: ComputedRef<ReadonlyArray<string>> = computed((): ReadonlyArray<string> => {
+  const stride: number = Math.max(1, Math.trunc(props.step ?? 30));
+  const from: number = bound(props.min, 0);
+  const to: number = bound(props.max, 23 * 60 + 59);
+  const out: string[] = [];
+  for (let m = from; m <= to; m += stride) out.push(fromMinutes(m));
+  return out;
+});
+
+const value: ComputedRef<string> = computed((): string => normalise(props.modelValue));
+const selectedIndex: ComputedRef<number> = computed((): number => times.value.indexOf(value.value));
+const shown: ComputedRef<string> = computed((): string =>
+  value.value !== '' ? value.value : (props.placeholder ?? '--:--'),
+);
+const isPlaceholder: ComputedRef<boolean> = computed((): boolean => value.value === '');
+const isDisabled: ComputedRef<boolean> = computed((): boolean => props.disabled === true);
+const isReadonly: ComputedRef<boolean> = computed((): boolean => props.readonly === true);
+const isInvalid: ComputedRef<boolean> = computed((): boolean => props.invalid === true);
+const activeDescendant: ComputedRef<string | undefined> = computed((): string | undefined =>
+  open.value && highlighted.value >= 0 ? optionId(highlighted.value) : undefined,
+);
+
+/* The panel is `max-height:15rem` and scrolls: a highlight the reader cannot see is no highlight,
+   and with 48 half-hour options most of the list is out of view. */
+function revealHighlight(): void {
+  void nextTick((): void => {
+    const list: HTMLUListElement | null = panelEl.value;
+    if (list === null || highlighted.value < 0) return;
+    const opt: Element | undefined = list.children[highlighted.value];
+    if (opt instanceof HTMLElement) opt.scrollIntoView({ block: 'nearest' });
+  });
+}
+
+/* Clamped, not cyclic: FdyCombo wraps because its lists are short and a wrap is a quick way back
+   to the top. Here ArrowUp at 00:00 landing on 23:30 reads as a glitch. Matches the raw path. */
+function setHighlight(index: number): void {
+  const last: number = times.value.length - 1;
+  highlighted.value = last < 0 ? -1 : Math.min(last, Math.max(0, index));
+  revealHighlight();
+}
+
+function openList(): void {
+  if (isDisabled.value || isReadonly.value || open.value) return;
+  open.value = true;
+  setHighlight(selectedIndex.value >= 0 ? selectedIndex.value : 0);
+}
+
+function closeList(focusTrigger: boolean): void {
+  if (!open.value) return;
+  open.value = false;
+  highlighted.value = -1;
+  if (focusTrigger) triggerEl.value?.focus();
+}
+
+function toggle(): void {
+  if (open.value) closeList(false);
+  else openList();
+}
+
+function choose(index: number): void {
+  const next: string | undefined = times.value[index];
+  if (next === undefined) return;
+  if (next !== value.value) {
+    emit('update:modelValue', next);
+    emit('change', next);
+  }
+  closeList(true);
+}
+
+function onKeydown(e: KeyboardEvent): void {
+  if (isDisabled.value || isReadonly.value) return;
+  switch (e.key) {
+    case 'ArrowDown':
+      e.preventDefault();
+      if (open.value) setHighlight(highlighted.value + 1);
+      else openList();
+      break;
+    case 'ArrowUp':
+      e.preventDefault();
+      if (open.value) setHighlight(highlighted.value - 1);
+      else openList();
+      break;
+    case 'Home':
+      if (open.value) {
+        e.preventDefault();
+        setHighlight(0);
+      }
+      break;
+    case 'End':
+      if (open.value) {
+        e.preventDefault();
+        setHighlight(times.value.length - 1);
+      }
+      break;
+    case 'Enter':
+    case ' ':
+      e.preventDefault();
+      if (open.value && highlighted.value >= 0) choose(highlighted.value);
+      else openList();
+      break;
+    case 'Escape':
+      if (open.value) {
+        e.preventDefault();
+        closeList(true);
+      }
+      break;
+    case 'Tab':
+      if (open.value) closeList(false);
+      break;
+    default:
+      break;
+  }
+}
+
+function onDocPointerDown(e: MouseEvent): void {
+  const target: EventTarget | null = e.target;
+  if (rootEl.value !== null && target instanceof Node && !rootEl.value.contains(target)) {
+    closeList(false);
+  }
+}
+
+function onFocusout(e: FocusEvent): void {
+  const next: EventTarget | null = e.relatedTarget;
+  if (rootEl.value !== null && !(next instanceof Node && rootEl.value.contains(next))) {
+    closeList(false);
+  }
+}
+
+onMounted((): void => {
+  document.addEventListener('mousedown', onDocPointerDown);
+});
+onBeforeUnmount((): void => {
+  document.removeEventListener('mousedown', onDocPointerDown);
+});
+</script>
+
+<template>
+  <div
+    ref="rootEl"
+    class="fdy-timepicker"
+    :class="{ 'fdy-timepicker--error': isInvalid }"
+    :data-value="value"
+    :data-fdy-required="required === true ? '' : undefined"
+    @keydown="onKeydown"
+    @focusout="onFocusout"
+  >
+    <button
+      :id="triggerId"
+      ref="triggerEl"
+      type="button"
+      class="fdy-timepicker__trigger"
+      :class="{ 'is-open': open }"
+      aria-haspopup="listbox"
+      :aria-controls="panelId"
+      :aria-expanded="open"
+      :aria-activedescendant="activeDescendant"
+      :aria-label="ariaLabel"
+      :aria-labelledby="ariaLabelledby"
+      :aria-invalid="isInvalid ? 'true' : undefined"
+      :aria-readonly="isReadonly ? 'true' : undefined"
+      :aria-describedby="describedby"
+      :disabled="isDisabled"
+      @click="toggle"
+    >
+      <span class="fdy-timepicker__value" :class="{ 'fdy-timepicker__value--placeholder': isPlaceholder }">{{ shown }}</span>
+      <span class="fdy-timepicker__icon">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2"
+             stroke-linecap="round" stroke-linejoin="round" aria-hidden="true">
+          <circle cx="12" cy="12" r="9"></circle>
+          <path d="M12 7v5l3 2"></path>
+        </svg>
+      </span>
+    </button>
+    <ul :id="panelId" ref="panelEl" class="fdy-timepicker__panel" role="listbox"
+        :aria-label="ariaLabel" popover="manual" :hidden="!open">
+      <!-- @mousedown.prevent keeps focus on the trigger: an <li> isn't focusable, so a plain
+           mousedown moves focus out of the control, fires @focusout and closes the panel before
+           the click lands — mouse-select would silently do nothing. Same as FdyCombo. -->
+      <li
+        v-for="(t, i) in times"
+        :id="optionId(i)"
+        :key="t"
+        class="fdy-timepicker__opt"
+        :class="{ 'is-active': i === highlighted }"
+        role="option"
+        :aria-selected="t === value"
+        @mousedown.prevent
+        @click="choose(i)"
+        @mousemove="setHighlight(i)"
+      >{{ t }}</li>
+    </ul>
+  </div>
+</template>

package/adapters/vue/index.d.ts

@@ -44,6 +44,7 @@ export { default as FdyDatepicker } from './components/FdyDatepicker.vue';
 export { default as FdyMonthpicker } from './components/FdyMonthpicker.vue';
 export type { FdyMonth } from '../core/month-grid';
 export { default as FdyDateRange } from './components/FdyDateRange.vue';
+export { default as FdyTimepicker } from './components/FdyTimepicker.vue';
 export type { DateRangeValue } from './components/FdyDateRange.vue';
 export { default as FdyAutocomplete } from './components/FdyAutocomplete.vue';
 export { default as FdyCascade } from './components/FdyCascade.vue';

package/adapters/vue/index.js

@@ -4,6 +4,7 @@ export { default as FdyCombo } from './components/FdyCombo.vue';
 export { default as FdyDatepicker } from './components/FdyDatepicker.vue';
 export { default as FdyMonthpicker } from './components/FdyMonthpicker.vue';
 export { default as FdyDateRange } from './components/FdyDateRange.vue';
+export { default as FdyTimepicker } from './components/FdyTimepicker.vue';
 export { default as FdyAutocomplete } from './components/FdyAutocomplete.vue';
 export { default as FdyCascade } from './components/FdyCascade.vue';
 export { default as FdyCfl } from './components/FdyCfl.vue';

package/dist/freeday-cascade.js

@@ -198,6 +198,11 @@
       if (!node) return;
       if (node.children) { drill(i); return; }
       selectedValue = node.value;
+      /* Mirror the value onto the ROOT, which until now only seeded it. `freeday-select.js` has
+         always done this, so this makes the family agree rather than inventing a second idea, and
+         it is what lets `freeday-form.js` require a kit control without knowing which control it
+         is: one attribute instead of five event names (#096). */
+      wrap.setAttribute('data-value', node.value);
       var labels = stack.map(function (n) { return n.label; }).concat([node.label]);
       valueSpan.textContent = labels.join(sep);
       valueSpan.classList.remove('fdy-cascade__value--placeholder');

package/dist/freeday-datepicker.js

@@ -175,6 +175,11 @@
     wrap.appendChild(panel);
 
     function updateDisplay() {
+      /* Mirror the value onto the ROOT, which until now only seeded it. `freeday-select.js` has
+         always done this, so this makes the family agree rather than inventing a second idea, and
+         it is what lets `freeday-form.js` require a kit control without knowing which control it
+         is: one attribute instead of five event names (#096). */
+      wrap.setAttribute('data-value', selected ? (monthOnly ? toISOMonth(selected) : toISO(selected)) : '');
       if (selected) {
         /* Through the same `Intl` formatter the month CELLS and the day grid's title already use,
            which is the whole reason this mode exists: <input type="month"> names the month in the

package/dist/freeday-form.js

@@ -74,6 +74,36 @@
 
   function fieldOf(el) { return el.closest('.fdy-field') || el.parentElement; }
 
+  /* A kit control (combo, datepicker, monthpicker, timepicker, cascade) is NOT a form control.
+   * Its trigger is a <button>, so `willValidate` is false and `form.elements` never offers it --
+   * `required` on one meant nothing, and a form could not demand that it be filled (#096).
+   *
+   * Nothing here names a component. Two attributes carry it:
+   *   data-fdy-required  the app asking for it, on the control's ROOT
+   *   data-value         the live value, which every value-bearing kit control now mirrors
+   * and the element that takes aria-invalid and focus is found by `aria-haspopup`, which every
+   * popup-style kit trigger already sets. `FdyAutocomplete` and `FdyCfl` are absent on purpose:
+   * they render a real <input>, so the NATIVE `required` is what fits them, and routing them
+   * through here would give one field two sources of truth. No prop exposes that yet, which is a
+   * separate gap and is written down in NEXT-UP.md rather than half-closed here. */
+  function kitRoots(form) {
+    return Array.prototype.slice.call(form.querySelectorAll('[data-fdy-required]'));
+  }
+
+  /* The trigger, or the root itself if a control ever ships without one, so a missing trigger
+     degrades to a visible error rather than a thrown TypeError. */
+  function kitAria(root) {
+    return root.querySelector('[aria-haspopup]') || root;
+  }
+
+  function kitMessage(root) {
+    if ((root.getAttribute('data-value') || '') !== '') return '';
+    var form = root.closest('form');
+    return root.getAttribute('data-fdy-msg-required')
+      || root.getAttribute('data-fdy-msg')
+      || textOf(form, 'required');
+  }
+
   function ensureErrorEl(el) {
     var field = fieldOf(el);
     var errEl = field ? field.querySelector('[data-fdy-error]') : null;
@@ -164,6 +194,21 @@
     function controls() {
       return Array.prototype.filter.call(form.elements, isCandidate);
     }
+    function validateKit(root) {
+      var msg = kitMessage(root);
+      paint(kitAria(root), msg);
+      return !msg;
+    }
+    /* The value lives in an attribute, and each control changes it through its own event name
+       (fdy-change, fdy-datepicker-change, fdy-time-select, fdy-cascade-change). Observing the
+       attribute is what keeps this enhancer from having to know any of them. */
+    function kitLiveBind(root) {
+      if (root.dataset.fdyKitBound === '1') return;
+      root.dataset.fdyKitBound = '1';
+      new MutationObserver(function () {
+        if (submitted || eager) validateKit(root);
+      }).observe(root, { attributes: true, attributeFilter: ['data-value'] });
+    }
     function validateOne(el) {
       var msg = messageFor(el);
       paint(el, msg);
@@ -178,6 +223,7 @@
     }
 
     Array.prototype.forEach.call(controls(), liveBind);
+    kitRoots(form).forEach(kitLiveBind);
 
     form.addEventListener('submit', function (e) {
       submitted = true;
@@ -186,6 +232,18 @@
         liveBind(el);
         if (!validateOne(el)) invalid.push(el);
       });
+      kitRoots(form).forEach(function (root) {
+        kitLiveBind(root);
+        if (!validateKit(root)) invalid.push(kitAria(root));
+      });
+      /* DOM order, not native-then-kit: `invalid[0]` is what gets revealed and focused, and a
+         reader sent to the second field while the first is also red learns the wrong thing. */
+      invalid.sort(function (a, b) {
+        var rel = a.compareDocumentPosition(b);
+        if (rel & Node.DOCUMENT_POSITION_FOLLOWING) return -1;
+        if (rel & Node.DOCUMENT_POSITION_PRECEDING) return 1;
+        return 0;
+      });
       if (invalid.length) {
         e.preventDefault();
         reveal(invalid[0]);
@@ -202,11 +260,13 @@
         submitted = true;
         var invalid = [];
         Array.prototype.forEach.call(controls(), function (el) { if (!validateOne(el)) invalid.push(el); });
+        kitRoots(form).forEach(function (root) { if (!validateKit(root)) invalid.push(kitAria(root)); });
         return invalid;
       },
       reset: function () {
         submitted = false;
         Array.prototype.forEach.call(controls(), function (el) { paint(el, ''); });
+        kitRoots(form).forEach(function (root) { paint(kitAria(root), ''); });
       }
     };
     form._fdyForm = api;

package/dist/freeday-timepicker.js

@@ -59,6 +59,14 @@
     trigger.setAttribute('aria-haspopup', 'listbox');
     trigger.setAttribute('aria-expanded', 'false');
     trigger.setAttribute('aria-label', label);
+    /* The trigger is a <button>, which is NOT a labelable element, so a form's own `<label for>`
+       can never activate it -- but an id is still what `aria-describedby` targets and what a host
+       needs to point at this control. Both were unreadable from the seed until now, so a Blazor
+       host could not name its own error text. Mirrors the datepicker's seed. */
+    var seedId = wrap.getAttribute('data-id');
+    if (seedId) trigger.id = seedId;
+    var describedby = wrap.getAttribute('data-describedby');
+    if (describedby) trigger.setAttribute('aria-describedby', describedby);
     var valueSpan = document.createElement('span');
     valueSpan.className = 'fdy-timepicker__value';
     trigger.appendChild(valueSpan);
@@ -96,8 +104,37 @@
     wrap.appendChild(panel);
 
     var active = -1;
+    /* A host that renders its seed ONCE and then never re-renders it (Blazor: ShouldRender is
+       false after hydration) still has to be able to disable, lock or invalidate the field
+       afterwards. Without this the parameter was there and nothing read it. Mirrors
+       FreedayDatepicker.setState so the two controls of one family answer the same call. */
+    var stateDisabled = wrap.hasAttribute('data-disabled');
+    var stateReadonly = wrap.hasAttribute('data-readonly');
+    var stateInvalid = wrap.hasAttribute('data-invalid');
+
+    function applyState() {
+      trigger.disabled = stateDisabled;
+      if (stateReadonly) trigger.setAttribute('aria-readonly', 'true');
+      else trigger.removeAttribute('aria-readonly');
+      if (stateInvalid) trigger.setAttribute('aria-invalid', 'true');
+      else trigger.removeAttribute('aria-invalid');
+      wrap.classList.toggle('fdy-timepicker--error', stateInvalid);
+      if ((stateDisabled || stateReadonly) && !panel.hidden) close(false);
+    }
+    function setState(next) {
+      if (!next) return;
+      if (next.disabled != null) stateDisabled = !!next.disabled;
+      if (next.readonly != null) stateReadonly = !!next.readonly;
+      if (next.invalid != null) stateInvalid = !!next.invalid;
+      applyState();
+    }
 
     function updateDisplay() {
+      /* Mirror the value onto the ROOT, which until now only seeded it. `freeday-select.js` has
+         always done this, so this makes the family agree rather than inventing a second idea, and
+         it is what lets `freeday-form.js` require a kit control without knowing which control it
+         is: one attribute instead of five event names (#096). */
+      wrap.setAttribute('data-value', value);
       if (value) {
         valueSpan.textContent = value;
         valueSpan.classList.remove('fdy-timepicker__value--placeholder');
@@ -124,6 +161,7 @@
     var _pop = null;
     function popCtl() { if (_pop === null && window.FreedayPopover) _pop = window.FreedayPopover.attach(panel, trigger); return _pop; }
     function open() {
+      if (stateDisabled || stateReadonly) return;
       if (!panel.hidden) return;
       var p = popCtl(); if (p) p.show(); else panel.hidden = false;
       trigger.setAttribute('aria-expanded', 'true');
@@ -174,10 +212,12 @@
     });
 
     updateDisplay();
+    applyState();
 
     var api = {
       wrap: wrap,
       getValue: function () { return value; },
+      setState: setState,
       clear: function () { value = ''; for (var i = 0; i < opts.length; i++) opts[i].setAttribute('aria-selected', 'false'); updateDisplay(); }
     };
     wrap._fdyTp = api;
@@ -197,5 +237,13 @@
     initAll();
   }
 
-  window.FreedayTimepicker = { init: initTime, initAll: initAll };
+  window.FreedayTimepicker = {
+    init: initTime,
+    initAll: initAll,
+    /* See api.setState above: the one call a render-once host needs. */
+    setState: function (root, state) {
+      var api = root && root._fdyTp ? root._fdyTp : null;
+      if (api && api.setState) api.setState(state);
+    }
+  };
 })();