@cahyo-dimas/freeday 3.7.0 → 3.8.0

package/dist/freeday-popover.js

@@ -8,7 +8,8 @@
  * Used by the select/combo, datepicker, timepicker, cascade, autocomplete and menu enhancers;
  * the freeday/vue adapter ships an equivalent `usePopover` composable.
  *
- * attach(panel, trigger) -> { show(), hide() }. show()/hide() also toggle the panel's [hidden]
+ * attach(panel, trigger, opts) -> { show(), hide() }, where opts is { matchWidth, align } and
+ * both are described on place() below. show()/hide() also toggle the panel's [hidden]
  * attribute so callers keep using `!panel.hidden` for open-state and the `:not([hidden])`
  * entrance animation still fires. On browsers without the Popover API it degrades to that
  * [hidden] toggle over the panel's existing absolute-positioned CSS (clipped, but functional).
@@ -21,35 +22,56 @@
     && typeof HTMLElement.prototype.showPopover === 'function';
 
   // Position `panel` (already shown, so it has a measurable box) against `trigger`'s rect.
-  // matchWidth (default true) floors the panel to the trigger width, right for input-shaped
-  // dropdowns (combo/cascade/date/time), skipped for menus that keep their own min-width.
-  function place(panel, trigger, matchWidth) {
-    var r = trigger.getBoundingClientRect();
+  // opts is the object attach() takes, and both keys are optional:
+  //   matchWidth  (default true) floors the panel to the trigger width, right for input-shaped
+  //               dropdowns (combo/cascade/date/time), skipped for menus that keep their own min-width.
+  //   align       'start' (default) lines the panel's LEFT edge up with the trigger's left edge;
+  //               'end' lines its RIGHT edge up with the trigger's right edge, which is what a
+  //               control parked in a right-hand gutter needs. The panel is kept inside the
+  //               viewport either way, so 'end' near the left edge slides right instead of
+  //               hanging off it. freeday-menu.js reads it off `.fdy-menu--end`.
+  function place(panel, trigger, opts) {
+    var o = opts || {};
+    /* Take the panel out of the flow BEFORE measuring anything, because until this runs the panel
+     * is still `position:absolute` with `top:calc(100% + …)` from its component's stylesheet. An
+     * author rule outranks the popover UA style, and in the top layer that `100%` resolves against
+     * the viewport, so a panel that has just been shown sits one viewport height down the page and
+     * drags the document's scrollable overflow with it. Where scrollbars take layout space (every
+     * Windows and Linux browser; macOS overlay scrollbars hide it completely) the document gains a
+     * classic scrollbar for the duration, documentElement.clientWidth drops by its width, and the
+     * page relays out 15px narrower. A trigger rect read in that instant is a rect from a layout
+     * that is about to be undone by the next three lines: measured 961 instead of 976 for an avatar
+     * in a 24px gutter, so the menu landed a scrollbar's width to the left of it. */
     panel.style.position = 'fixed';
     panel.style.margin = '0';
     panel.style.inset = 'auto';                 // clear the UA popover centering
-    if (matchWidth !== false) panel.style.minWidth = r.width + 'px'; // at least as wide as the trigger
+    var r = trigger.getBoundingClientRect();
+    if (o.matchWidth !== false) panel.style.minWidth = r.width + 'px'; // at least as wide as the trigger
     var ph = panel.offsetHeight, pw = panel.offsetWidth;
     var vw = document.documentElement.clientWidth, vh = document.documentElement.clientHeight;
     var below = vh - r.bottom - GAP, above = r.top - GAP;
     // Prefer below; flip above only when it doesn't fit below and above has more room.
     var top = (ph <= below || below >= above) ? (r.bottom + GAP) : Math.max(GAP, r.top - GAP - ph);
-    var left = r.left;
-    if (left + pw > vw - GAP) left = Math.max(GAP, vw - GAP - pw); // keep within the viewport
+    var left = (o.align === 'end') ? (r.right - pw) : r.left;
+    /* Clamped on BOTH sides, and that is not belt-and-braces: the first line is what keeps a
+       start-aligned panel on screen, the second is what keeps an end-aligned one on screen when
+       the panel is wider than the room to the left of its trigger. Keeping only one of them
+       trades an overflow on one edge for an overflow on the other. */
+    if (left + pw > vw - GAP) left = vw - GAP - pw;
+    if (left < GAP) left = GAP;
     panel.style.top = Math.round(top) + 'px';
     panel.style.left = Math.round(left) + 'px';
   }
 
   function attach(panel, trigger, opts) {
-    var matchWidth = !(opts && opts.matchWidth === false);
     if (supported) panel.setAttribute('popover', 'manual');
-    function reposition() { if (supported && panel.matches(':popover-open')) place(panel, trigger, matchWidth); }
+    function reposition() { if (supported && panel.matches(':popover-open')) place(panel, trigger, opts); }
     return {
       show: function () {
         panel.hidden = false;
         if (supported) {
           if (!panel.matches(':popover-open')) panel.showPopover();
-          place(panel, trigger, matchWidth);
+          place(panel, trigger, opts);
           window.addEventListener('scroll', reposition, true); // capture: any scrolling ancestor
           window.addEventListener('resize', reposition);
         }

package/dist/freeday-tabs.js

@@ -4,6 +4,12 @@
  * Markup: a [data-fdy-tabs] with a [role="tablist"] of
  * <button role="tab" aria-controls="PANEL" aria-selected> and matching
  * <div role="tabpanel" id="PANEL" aria-labelledby="TAB" [hidden]>.
+ *
+ * The arrow AXIS comes from the tablist's `aria-orientation`: `vertical` answers to Up and
+ * Down, anything else to Left and Right. One axis per tablist, which is what APG maps, and the
+ * other pair is left entirely alone rather than bound as a second axis: Left and Right over a
+ * column of tabs belong to whatever else is on the page, and a widget that preventDefaults a key
+ * it has no meaning for has taken it from the page silently. Home/End answer on both.
  */
 (function () {
   'use strict';
@@ -14,6 +20,19 @@
     if (tabs.length === 0) return;
     root.dataset.fdyTabsReady = '1';
 
+    /* The look follows `.fdy-tabs--vertical`, the behaviour follows `aria-orientation`, and this
+       makes the second agree with the first so an app states the axis once. The attribute always
+       wins when it is there: it is what an assistive technology announces, so nothing here may
+       overwrite one an author wrote. */
+    var list = root.querySelector('[role="tablist"]');
+    if (list !== null && list.getAttribute('aria-orientation') === null
+        && root.classList.contains('fdy-tabs--vertical')) {
+      list.setAttribute('aria-orientation', 'vertical');
+    }
+    var vertical = list !== null && list.getAttribute('aria-orientation') === 'vertical';
+    var NEXT_KEY = vertical ? 'ArrowDown' : 'ArrowRight';
+    var PREV_KEY = vertical ? 'ArrowUp' : 'ArrowLeft';
+
     function panelFor(tab) {
       var id = tab.getAttribute('aria-controls');
       return id ? document.getElementById(id) : null;
@@ -33,9 +52,9 @@
       tab.addEventListener('click', function () { select(tab, false); });
       tab.addEventListener('keydown', function (e) {
         switch (e.key) {
-          case 'ArrowRight':
+          case NEXT_KEY:
             e.preventDefault(); select(tabs[(i + 1) % tabs.length], true); break;
-          case 'ArrowLeft':
+          case PREV_KEY:
             e.preventDefault(); select(tabs[(i - 1 + tabs.length) % tabs.length], true); break;
           case 'Home':
             e.preventDefault(); select(tabs[0], true); break;

package/dist/freeday.bundle.css

@@ -3056,6 +3056,37 @@ fieldset.fdy-field>legend{padding:0;float:none;margin-bottom:var(--space-2);}
 /* Reveal the newly-shown panel on tab switch (fade + rise), reduced-motion gated. */
 @media (prefers-reduced-motion:no-preference){.fdy-tabs__panel:not([hidden]){animation:fdy-combo-in var(--dur-base) var(--ease-standard);}}
 
+/* VERTICAL VARIANT: the same tabs turned down the page, list on the leading side, panel beside it.
+ *
+ * Two markers, one each, and they are not interchangeable. The CLASS decides the look, because a
+ * stylesheet cannot reach a parent from a child and the two-column box belongs to `.fdy-tabs`
+ * itself. The ATTRIBUTE `aria-orientation="vertical"` on the tablist decides the keyboard, because
+ * that is the thing an assistive technology announces and APG requires it on a vertical tablist
+ * anyway. `freeday-tabs.js` writes the attribute when only the class is present, so an app states
+ * the axis once and the two can never disagree.
+ *
+ * Selection is a SOFT FILL here, not a leading edge bar. Sideways, the marker is an underline under
+ * the tab it belongs to; turned 90 degrees that line lands between two tabs and points at the wrong
+ * one. The kit already has an answer for "one item in a vertical list is where you are" and spends
+ * it in four places (`.fdy-nav__item[aria-current]`, the combo, cascade and autocomplete options):
+ * `--color-primary-soft` behind `--color-primary-strong`. Both are precomputed tone tokens, so this
+ * needs no color-mix() and no alpha of its own.
+ *
+ * What it deliberately does NOT do: pick a column width (set `--fdy-tabs-list-w`, default `auto`),
+ * and collapse to one column on a narrow screen. Whether these tabs are a whole page, a card or a
+ * drawer is the page's knowledge, not the component's, so the breakpoint is the page's to write. */
+.fdy-tabs--vertical{display:flex;align-items:flex-start;gap:var(--space-5);}
+/* `overflow:visible` on both axes, because the base strip scrolls sideways: a scroll container
+   clips to its padding box, and a column has no sideways overflow to scroll, only a focus ring to
+   lose. `box-shadow:none` drops the strip's own bottom line with it. */
+.fdy-tabs--vertical .fdy-tabs__list{flex:none;flex-direction:column;width:var(--fdy-tabs-list-w,auto);overflow:visible;box-shadow:none;}
+/* `white-space:normal` and `text-align:start` are corrections, not taste: a tab in a column of
+   fixed width that may not wrap will overflow it, and a button centres its label by default. */
+.fdy-tabs--vertical .fdy-tabs__tab{border-bottom:0;border-radius:var(--radius-md);text-align:start;white-space:normal;}
+.fdy-tabs--vertical .fdy-tabs__tab:focus-visible{border-radius:var(--radius-md);}
+.fdy-tabs--vertical .fdy-tabs__tab[aria-selected="true"],.fdy-tabs--vertical .fdy-tabs__tab[aria-current="page"]{background:var(--color-primary-soft);color:var(--color-primary-strong);font-weight:var(--weight-semibold);}
+.fdy-tabs--vertical .fdy-tabs__panel{flex:1;min-width:0;padding:0;}
+
 /* Freeday. Timeline (vertical event feed: dot markers on a connector line). Pure CSS. */
 .fdy-timeline{list-style:none;margin:0;padding:0;}
 .fdy-timeline__item{position:relative;padding:0 0 var(--space-5) var(--space-6);border-left:2px solid var(--color-border);}

package/dist/freeday.css

@@ -1879,6 +1879,37 @@ fieldset.fdy-field>legend{padding:0;float:none;margin-bottom:var(--space-2);}
 /* Reveal the newly-shown panel on tab switch (fade + rise), reduced-motion gated. */
 @media (prefers-reduced-motion:no-preference){.fdy-tabs__panel:not([hidden]){animation:fdy-combo-in var(--dur-base) var(--ease-standard);}}
 
+/* VERTICAL VARIANT: the same tabs turned down the page, list on the leading side, panel beside it.
+ *
+ * Two markers, one each, and they are not interchangeable. The CLASS decides the look, because a
+ * stylesheet cannot reach a parent from a child and the two-column box belongs to `.fdy-tabs`
+ * itself. The ATTRIBUTE `aria-orientation="vertical"` on the tablist decides the keyboard, because
+ * that is the thing an assistive technology announces and APG requires it on a vertical tablist
+ * anyway. `freeday-tabs.js` writes the attribute when only the class is present, so an app states
+ * the axis once and the two can never disagree.
+ *
+ * Selection is a SOFT FILL here, not a leading edge bar. Sideways, the marker is an underline under
+ * the tab it belongs to; turned 90 degrees that line lands between two tabs and points at the wrong
+ * one. The kit already has an answer for "one item in a vertical list is where you are" and spends
+ * it in four places (`.fdy-nav__item[aria-current]`, the combo, cascade and autocomplete options):
+ * `--color-primary-soft` behind `--color-primary-strong`. Both are precomputed tone tokens, so this
+ * needs no color-mix() and no alpha of its own.
+ *
+ * What it deliberately does NOT do: pick a column width (set `--fdy-tabs-list-w`, default `auto`),
+ * and collapse to one column on a narrow screen. Whether these tabs are a whole page, a card or a
+ * drawer is the page's knowledge, not the component's, so the breakpoint is the page's to write. */
+.fdy-tabs--vertical{display:flex;align-items:flex-start;gap:var(--space-5);}
+/* `overflow:visible` on both axes, because the base strip scrolls sideways: a scroll container
+   clips to its padding box, and a column has no sideways overflow to scroll, only a focus ring to
+   lose. `box-shadow:none` drops the strip's own bottom line with it. */
+.fdy-tabs--vertical .fdy-tabs__list{flex:none;flex-direction:column;width:var(--fdy-tabs-list-w,auto);overflow:visible;box-shadow:none;}
+/* `white-space:normal` and `text-align:start` are corrections, not taste: a tab in a column of
+   fixed width that may not wrap will overflow it, and a button centres its label by default. */
+.fdy-tabs--vertical .fdy-tabs__tab{border-bottom:0;border-radius:var(--radius-md);text-align:start;white-space:normal;}
+.fdy-tabs--vertical .fdy-tabs__tab:focus-visible{border-radius:var(--radius-md);}
+.fdy-tabs--vertical .fdy-tabs__tab[aria-selected="true"],.fdy-tabs--vertical .fdy-tabs__tab[aria-current="page"]{background:var(--color-primary-soft);color:var(--color-primary-strong);font-weight:var(--weight-semibold);}
+.fdy-tabs--vertical .fdy-tabs__panel{flex:1;min-width:0;padding:0;}
+
 /* Freeday. Timeline (vertical event feed: dot markers on a connector line). Pure CSS. */
 .fdy-timeline{list-style:none;margin:0;padding:0;}
 .fdy-timeline__item{position:relative;padding:0 0 var(--space-5) var(--space-6);border-left:2px solid var(--color-border);}

package/dist/freeday.js

@@ -2098,6 +2098,8 @@
  *               <div data-fdy-datepicker data-role="to" data-placeholder="To"></div>
  *             </div>
  *    The range links the two: the end can never precede the start (out-of-range days disable).
+ *  - Month:  <div data-fdy-datepicker data-mode="month" data-value="2026-10"></div>
+ *    The calendar opens ON the month grid and stops there; the value is "YYYY-MM".
  *
  * Emits a bubbling "fdy-datepicker-change" CustomEvent on the wrapper: detail {value, date}.
  * Keyboard in the grid: ←/→ ±1 day, ↑/↓ ±1 week, Home/End week edge, PageUp/Down ±month,
@@ -2126,6 +2128,11 @@
   var TEXT = {
     label: 'Date',
     placeholder: 'Choose a date',
+    /* The month mode's own pair. Reusing `label` and `placeholder` would name a month field "Date"
+       and ask the reader to "Choose a date" on a control that cannot express a day, so every caller
+       would have to pass both attributes to undo a default that was simply wrong for the mode. */
+    labelMonth: 'Month',
+    placeholderMonth: 'Choose a month',
     prevMonth: 'Previous month',
     nextMonth: 'Next month',
     prevYear: 'Previous year',
@@ -2156,6 +2163,7 @@
   function uid(p) { uidSeq += 1; return p + '-' + uidSeq; }
   function pad(n) { return n < 10 ? '0' + n : '' + n; }
   function toISO(d) { return d.getFullYear() + '-' + pad(d.getMonth() + 1) + '-' + pad(d.getDate()); }
+  function toISOMonth(d) { return d.getFullYear() + '-' + pad(d.getMonth() + 1); }
   function parseISO(s) {
     if (!s) return null;
     var p = String(s).split('-');
@@ -2163,6 +2171,17 @@
     var d = new Date(Number(p[0]), Number(p[1]) - 1, Number(p[2]));
     return isNaN(d.getTime()) ? null : d;
   }
+  /* Month mode reads BOTH shapes, and the day it drops is the point: a bound of "2026-03" lands on
+     March 1st, and monthDisabled then compares a whole month against it correctly at either end,
+     so an app can pass the same strings it stores. A full date still works for a host that keeps
+     its bounds in one format across a form. */
+  function parseISOMonth(s) {
+    if (!s) return null;
+    var p = String(s).split('-');
+    if (p.length < 2) return null;
+    var d = new Date(Number(p[0]), Number(p[1]) - 1, p.length > 2 ? Number(p[2]) : 1);
+    return isNaN(d.getTime()) ? null : d;
+  }
   function startOfDay(d) { return new Date(d.getFullYear(), d.getMonth(), d.getDate()); }
   function sameDay(a, b) { return !!a && !!b && a.getFullYear() === b.getFullYear() && a.getMonth() === b.getMonth() && a.getDate() === b.getDate(); }
   function addDays(d, n) { var x = new Date(d); x.setDate(x.getDate() + n); return x; }
@@ -2189,11 +2208,16 @@
     wrap.dataset.fdyDpReady = '1';
     wrap.classList.add('fdy-datepicker');
 
-    var placeholder = wrap.getAttribute('data-placeholder') || textOf(wrap, 'placeholder');
-    var label = wrap.getAttribute('data-label') || textOf(wrap, 'label');
-    var selected = parseISO(wrap.getAttribute('data-value'));
-    var minDate = parseISO(wrap.getAttribute('data-min'));
-    var maxDate = parseISO(wrap.getAttribute('data-max'));
+    /* `data-mode="month"` makes the month grid the DESTINATION rather than a waypoint: the panel
+       opens on it, Enter and a click commit from it, the day grid is never built, and the value is
+       "YYYY-MM". Anything else, including the attribute's absence, is the day picker unchanged. */
+    var monthOnly = wrap.getAttribute('data-mode') === 'month';
+    var parseVal = monthOnly ? parseISOMonth : parseISO;
+    var placeholder = wrap.getAttribute('data-placeholder') || textOf(wrap, monthOnly ? 'placeholderMonth' : 'placeholder');
+    var label = wrap.getAttribute('data-label') || textOf(wrap, monthOnly ? 'labelMonth' : 'label');
+    var selected = parseVal(wrap.getAttribute('data-value'));
+    var minDate = parseVal(wrap.getAttribute('data-min'));
+    var maxDate = parseVal(wrap.getAttribute('data-max'));
     var rangeStart = null, rangeEnd = null; // for in-range shading
     var view = startOfDay(selected || new Date());
     view = new Date(view.getFullYear(), view.getMonth(), 1);
@@ -2203,7 +2227,7 @@
        August 2026 to March 2022 is fifty-three of them. Shift+PageUp already jumped a year, but a
        shortcut nobody can see is not an affordance, the repo's own test helper clicked "previous
        month" twenty-four times to reach a date two years back. */
-    var mode = 'days';
+    var mode = monthOnly ? 'months' : 'days';
     var focusMonth = null;
     var focusYear = null;
 
@@ -2239,7 +2263,10 @@
 
     function updateDisplay() {
       if (selected) {
-        valueSpan.textContent = valueFmt.format(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
+           browser's language, this names it in the page's. */
+        valueSpan.textContent = (monthOnly ? monthNameFmt : valueFmt).format(selected);
         valueSpan.classList.remove('fdy-datepicker__value--placeholder');
       } else {
         valueSpan.textContent = placeholder;
@@ -2283,6 +2310,10 @@
     }
 
     function render() {
+      /* The floor of the drill, stated once here rather than at every caller that could lower it:
+         in month mode there is no level below months, so the day grid is unreachable by
+         construction instead of by every path remembering not to ask for it. */
+      if (monthOnly && mode === 'days') mode = 'months';
       if (mode === 'years') { renderYears(); return; }
       if (mode === 'months') { renderMonths(); return; }
       panel.innerHTML = '';
@@ -2387,7 +2418,7 @@
         }
         if (monthDisabled(year, m)) btn.disabled = true;
         btn.tabIndex = m === focusMonth ? 0 : -1;
-        btn.addEventListener('click', (function (mm) { return function () { openMonth(mm); }; })(m));
+        btn.addEventListener('click', (function (mm) { return function () { chooseMonth(mm); }; })(m));
         grid.appendChild(btn);
       }
       grid.addEventListener('keydown', onMonthKey);
@@ -2501,6 +2532,28 @@
       if (cell) cell.focus();
     }
 
+    /* What a month cell DOES, decided in one place for the click handler and the Enter key alike.
+       In day mode a month is a step on the way down; in month mode it is the answer. */
+    function chooseMonth(m) {
+      if (monthOnly) pickMonth(m);
+      else openMonth(m);
+    }
+
+    function pickMonth(m) {
+      var year = view.getFullYear();
+      if (monthDisabled(year, m)) return;
+      selected = new Date(year, m, 1);
+      focusMonth = m;
+      focusDate = selected;
+      updateDisplay();
+      /* The same event name, so a host already listening keeps listening, and `date` is still a
+         real Date (the first of the month) rather than a second shape to parse. */
+      wrap.dispatchEvent(new CustomEvent('fdy-datepicker-change', {
+        bubbles: true, detail: { value: toISOMonth(selected), date: new Date(selected) }
+      }));
+      close(true);
+    }
+
     /* Picking a month is navigation, not selection: it drops back to the day grid with the roving
        cell clamped into the new month, so nothing is committed until a DAY is chosen. */
     function openMonth(m) {
@@ -2532,7 +2585,7 @@
         case 'PageUp': moveMonthFocus(focusMonth, -1); break;
         case 'PageDown': moveMonthFocus(focusMonth, 1); break;
         case 'Enter':
-        case ' ': openMonth(focusMonth); break;
+        case ' ': chooseMonth(focusMonth); break;
         case 'Escape': close(true); break;
         default: handled = false;
       }
@@ -2626,14 +2679,15 @@
     function open() {
       if (stateDisabled || stateReadonly) return;
       if (!panel.hidden) return;
-      mode = 'days';
+      mode = monthOnly ? 'months' : 'days';
       focusDate = selected || focusDate || new Date();
       view = new Date(focusDate.getFullYear(), focusDate.getMonth(), 1);
+      if (monthOnly) focusMonth = view.getMonth();
       var p = popCtl(); if (p) p.show(); else panel.hidden = false;
       trigger.setAttribute('aria-expanded', 'true');
       trigger.classList.add('is-open');
       render();
-      focusFocusDate();
+      if (monthOnly) focusMonthCell(); else focusFocusDate();
       document.addEventListener('click', onDocClick, true);
     }
 
@@ -2659,10 +2713,10 @@
     var api = {
       wrap: wrap,
       setState: setState,
-      getValue: function () { return selected ? toISO(selected) : ''; },
+      getValue: function () { return selected ? (monthOnly ? toISOMonth(selected) : toISO(selected)) : ''; },
       clear: function () { selected = null; updateDisplay(); if (!panel.hidden) render(); },
-      setMin: function (iso) { minDate = parseISO(iso); if (!panel.hidden) render(); },
-      setMax: function (iso) { maxDate = parseISO(iso); if (!panel.hidden) render(); },
+      setMin: function (iso) { minDate = parseVal(iso); if (!panel.hidden) render(); },
+      setMax: function (iso) { maxDate = parseVal(iso); if (!panel.hidden) render(); },
       setRange: function (fromIso, toIso) {
         rangeStart = parseISO(fromIso);
         rangeEnd = parseISO(toIso);
@@ -3295,7 +3349,21 @@
       its[(index + its.length) % its.length].focus();
     }
     var _pop = null;
-    function popCtl() { if (_pop === null && window.FreedayPopover) _pop = window.FreedayPopover.attach(menu, trigger, { matchWidth: false }); return _pop; }
+    /* `.fdy-menu--end` is the kit's existing spelling for "align this menu to the right", and the
+       stylesheet has always honoured it (left:auto;right:0). The popover path replaces that with
+       inline `fixed` coordinates, so without this line the class was silently dropped the moment
+       the menu went into the top layer: an account menu in a page gutter overshot its avatar and
+       ran to 4px off the screen edge. Reported from an app that patched it with a `translate`
+       hack keyed to the kit's own GAP. */
+    function popCtl() {
+      if (_pop === null && window.FreedayPopover) {
+        _pop = window.FreedayPopover.attach(menu, trigger, {
+          matchWidth: false,
+          align: menu.classList.contains('fdy-menu--end') ? 'end' : 'start'
+        });
+      }
+      return _pop;
+    }
     function open(index) {
       var p = popCtl(); if (p) p.show(); else menu.hidden = false;
       trigger.setAttribute('aria-expanded', 'true');
@@ -3469,7 +3537,8 @@
  * Used by the select/combo, datepicker, timepicker, cascade, autocomplete and menu enhancers;
  * the freeday/vue adapter ships an equivalent `usePopover` composable.
  *
- * attach(panel, trigger) -> { show(), hide() }. show()/hide() also toggle the panel's [hidden]
+ * attach(panel, trigger, opts) -> { show(), hide() }, where opts is { matchWidth, align } and
+ * both are described on place() below. show()/hide() also toggle the panel's [hidden]
  * attribute so callers keep using `!panel.hidden` for open-state and the `:not([hidden])`
  * entrance animation still fires. On browsers without the Popover API it degrades to that
  * [hidden] toggle over the panel's existing absolute-positioned CSS (clipped, but functional).
@@ -3482,35 +3551,56 @@
     && typeof HTMLElement.prototype.showPopover === 'function';
 
   // Position `panel` (already shown, so it has a measurable box) against `trigger`'s rect.
-  // matchWidth (default true) floors the panel to the trigger width, right for input-shaped
-  // dropdowns (combo/cascade/date/time), skipped for menus that keep their own min-width.
-  function place(panel, trigger, matchWidth) {
-    var r = trigger.getBoundingClientRect();
+  // opts is the object attach() takes, and both keys are optional:
+  //   matchWidth  (default true) floors the panel to the trigger width, right for input-shaped
+  //               dropdowns (combo/cascade/date/time), skipped for menus that keep their own min-width.
+  //   align       'start' (default) lines the panel's LEFT edge up with the trigger's left edge;
+  //               'end' lines its RIGHT edge up with the trigger's right edge, which is what a
+  //               control parked in a right-hand gutter needs. The panel is kept inside the
+  //               viewport either way, so 'end' near the left edge slides right instead of
+  //               hanging off it. freeday-menu.js reads it off `.fdy-menu--end`.
+  function place(panel, trigger, opts) {
+    var o = opts || {};
+    /* Take the panel out of the flow BEFORE measuring anything, because until this runs the panel
+     * is still `position:absolute` with `top:calc(100% + …)` from its component's stylesheet. An
+     * author rule outranks the popover UA style, and in the top layer that `100%` resolves against
+     * the viewport, so a panel that has just been shown sits one viewport height down the page and
+     * drags the document's scrollable overflow with it. Where scrollbars take layout space (every
+     * Windows and Linux browser; macOS overlay scrollbars hide it completely) the document gains a
+     * classic scrollbar for the duration, documentElement.clientWidth drops by its width, and the
+     * page relays out 15px narrower. A trigger rect read in that instant is a rect from a layout
+     * that is about to be undone by the next three lines: measured 961 instead of 976 for an avatar
+     * in a 24px gutter, so the menu landed a scrollbar's width to the left of it. */
     panel.style.position = 'fixed';
     panel.style.margin = '0';
     panel.style.inset = 'auto';                 // clear the UA popover centering
-    if (matchWidth !== false) panel.style.minWidth = r.width + 'px'; // at least as wide as the trigger
+    var r = trigger.getBoundingClientRect();
+    if (o.matchWidth !== false) panel.style.minWidth = r.width + 'px'; // at least as wide as the trigger
     var ph = panel.offsetHeight, pw = panel.offsetWidth;
     var vw = document.documentElement.clientWidth, vh = document.documentElement.clientHeight;
     var below = vh - r.bottom - GAP, above = r.top - GAP;
     // Prefer below; flip above only when it doesn't fit below and above has more room.
     var top = (ph <= below || below >= above) ? (r.bottom + GAP) : Math.max(GAP, r.top - GAP - ph);
-    var left = r.left;
-    if (left + pw > vw - GAP) left = Math.max(GAP, vw - GAP - pw); // keep within the viewport
+    var left = (o.align === 'end') ? (r.right - pw) : r.left;
+    /* Clamped on BOTH sides, and that is not belt-and-braces: the first line is what keeps a
+       start-aligned panel on screen, the second is what keeps an end-aligned one on screen when
+       the panel is wider than the room to the left of its trigger. Keeping only one of them
+       trades an overflow on one edge for an overflow on the other. */
+    if (left + pw > vw - GAP) left = vw - GAP - pw;
+    if (left < GAP) left = GAP;
     panel.style.top = Math.round(top) + 'px';
     panel.style.left = Math.round(left) + 'px';
   }
 
   function attach(panel, trigger, opts) {
-    var matchWidth = !(opts && opts.matchWidth === false);
     if (supported) panel.setAttribute('popover', 'manual');
-    function reposition() { if (supported && panel.matches(':popover-open')) place(panel, trigger, matchWidth); }
+    function reposition() { if (supported && panel.matches(':popover-open')) place(panel, trigger, opts); }
     return {
       show: function () {
         panel.hidden = false;
         if (supported) {
           if (!panel.matches(':popover-open')) panel.showPopover();
-          place(panel, trigger, matchWidth);
+          place(panel, trigger, opts);
           window.addEventListener('scroll', reposition, true); // capture: any scrolling ancestor
           window.addEventListener('resize', reposition);
         }
@@ -4653,6 +4743,12 @@
  * Markup: a [data-fdy-tabs] with a [role="tablist"] of
  * <button role="tab" aria-controls="PANEL" aria-selected> and matching
  * <div role="tabpanel" id="PANEL" aria-labelledby="TAB" [hidden]>.
+ *
+ * The arrow AXIS comes from the tablist's `aria-orientation`: `vertical` answers to Up and
+ * Down, anything else to Left and Right. One axis per tablist, which is what APG maps, and the
+ * other pair is left entirely alone rather than bound as a second axis: Left and Right over a
+ * column of tabs belong to whatever else is on the page, and a widget that preventDefaults a key
+ * it has no meaning for has taken it from the page silently. Home/End answer on both.
  */
 (function () {
   'use strict';
@@ -4663,6 +4759,19 @@
     if (tabs.length === 0) return;
     root.dataset.fdyTabsReady = '1';
 
+    /* The look follows `.fdy-tabs--vertical`, the behaviour follows `aria-orientation`, and this
+       makes the second agree with the first so an app states the axis once. The attribute always
+       wins when it is there: it is what an assistive technology announces, so nothing here may
+       overwrite one an author wrote. */
+    var list = root.querySelector('[role="tablist"]');
+    if (list !== null && list.getAttribute('aria-orientation') === null
+        && root.classList.contains('fdy-tabs--vertical')) {
+      list.setAttribute('aria-orientation', 'vertical');
+    }
+    var vertical = list !== null && list.getAttribute('aria-orientation') === 'vertical';
+    var NEXT_KEY = vertical ? 'ArrowDown' : 'ArrowRight';
+    var PREV_KEY = vertical ? 'ArrowUp' : 'ArrowLeft';
+
     function panelFor(tab) {
       var id = tab.getAttribute('aria-controls');
       return id ? document.getElementById(id) : null;
@@ -4682,9 +4791,9 @@
       tab.addEventListener('click', function () { select(tab, false); });
       tab.addEventListener('keydown', function (e) {
         switch (e.key) {
-          case 'ArrowRight':
+          case NEXT_KEY:
             e.preventDefault(); select(tabs[(i + 1) % tabs.length], true); break;
-          case 'ArrowLeft':
+          case PREV_KEY:
             e.preventDefault(); select(tabs[(i - 1 + tabs.length) % tabs.length], true); break;
           case 'Home':
             e.preventDefault(); select(tabs[0], true); break;

package/docs/getting-started.md

@@ -191,7 +191,7 @@ live docs also have a copy button per component.
 ```bash
 npm i @cahyo-dimas/freeday
 ```
-Lands in `package.json` as `"@cahyo-dimas/freeday": "^3.7.0"` (public npm package). `dist/` is
+Lands in `package.json` as `"@cahyo-dimas/freeday": "^3.8.0"` (public npm package). `dist/` is
 committed and published → no build step; `npm ci` runs without auth.
 
 ### 2. Import the CSS + enhancers **once** in your entry (`src/main.ts`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cahyo-dimas/freeday",
-  "version": "3.7.0",
+  "version": "3.8.0",
   "description": "Freeday: token-driven, framework-agnostic UI KIT (design source-of-truth).",
   "type": "module",
   "license": "MIT",
@@ -96,7 +96,7 @@
   "scripts": {
     "build": "node tokens/build.mjs",
     "test": "node --test",
-    "test:browser": "node --test --test-concurrency=3 browser/color-mix.mjs browser/vanilla.mjs browser/adapter.mjs browser/layout.mjs browser/theme.mjs browser/state.mjs browser/root-init.mjs browser/upload-states.mjs browser/number.mjs browser/card-stretch.mjs browser/text-override.mjs browser/control-heights.mjs browser/field-width.mjs browser/cfl-multi.mjs browser/cfl-dialog-only.mjs browser/crowding.mjs browser/over-dialog.mjs browser/chart-scale.mjs browser/overlay-stack.mjs browser/chart-a11y.mjs browser/app-shell.mjs browser/bottom-nav.mjs browser/picker-states.mjs browser/tabs-strip.mjs browser/cfl-narrow.mjs browser/form-reveal.mjs browser/confirm-search-copy.mjs browser/daterange-settled.mjs browser/display-parts.mjs browser/table-empty.mjs browser/page-columns.mjs browser/table-hover.mjs browser/harness-contract.mjs",
+    "test:browser": "node --test --test-concurrency=3 browser/color-mix.mjs browser/vanilla.mjs browser/adapter.mjs browser/layout.mjs browser/theme.mjs browser/state.mjs browser/root-init.mjs browser/upload-states.mjs browser/number.mjs browser/card-stretch.mjs browser/text-override.mjs browser/control-heights.mjs browser/field-width.mjs browser/cfl-multi.mjs browser/cfl-dialog-only.mjs browser/crowding.mjs browser/over-dialog.mjs browser/chart-scale.mjs browser/overlay-stack.mjs browser/chart-a11y.mjs browser/app-shell.mjs browser/bottom-nav.mjs browser/picker-states.mjs browser/tabs-strip.mjs browser/tabs-vertical.mjs browser/menu-align.mjs browser/cfl-narrow.mjs browser/form-reveal.mjs browser/confirm-search-copy.mjs browser/daterange-settled.mjs browser/display-parts.mjs browser/table-empty.mjs browser/table-footer-text.mjs browser/month-mode.mjs browser/page-columns.mjs browser/table-hover.mjs browser/harness-contract.mjs",
     "prepack": "node tokens/build.mjs",
     "version": "node tokens/build.mjs && git add dist",
     "typecheck:react": "tsc -p adapters/react/tsconfig.json --noEmit",

package/src/components/tabs.css

@@ -32,3 +32,34 @@
 .fdy-tabs__panel[hidden]{display:none;}
 /* Reveal the newly-shown panel on tab switch (fade + rise), reduced-motion gated. */
 @media (prefers-reduced-motion:no-preference){.fdy-tabs__panel:not([hidden]){animation:fdy-combo-in var(--dur-base) var(--ease-standard);}}
+
+/* VERTICAL VARIANT: the same tabs turned down the page, list on the leading side, panel beside it.
+ *
+ * Two markers, one each, and they are not interchangeable. The CLASS decides the look, because a
+ * stylesheet cannot reach a parent from a child and the two-column box belongs to `.fdy-tabs`
+ * itself. The ATTRIBUTE `aria-orientation="vertical"` on the tablist decides the keyboard, because
+ * that is the thing an assistive technology announces and APG requires it on a vertical tablist
+ * anyway. `freeday-tabs.js` writes the attribute when only the class is present, so an app states
+ * the axis once and the two can never disagree.
+ *
+ * Selection is a SOFT FILL here, not a leading edge bar. Sideways, the marker is an underline under
+ * the tab it belongs to; turned 90 degrees that line lands between two tabs and points at the wrong
+ * one. The kit already has an answer for "one item in a vertical list is where you are" and spends
+ * it in four places (`.fdy-nav__item[aria-current]`, the combo, cascade and autocomplete options):
+ * `--color-primary-soft` behind `--color-primary-strong`. Both are precomputed tone tokens, so this
+ * needs no color-mix() and no alpha of its own.
+ *
+ * What it deliberately does NOT do: pick a column width (set `--fdy-tabs-list-w`, default `auto`),
+ * and collapse to one column on a narrow screen. Whether these tabs are a whole page, a card or a
+ * drawer is the page's knowledge, not the component's, so the breakpoint is the page's to write. */
+.fdy-tabs--vertical{display:flex;align-items:flex-start;gap:var(--space-5);}
+/* `overflow:visible` on both axes, because the base strip scrolls sideways: a scroll container
+   clips to its padding box, and a column has no sideways overflow to scroll, only a focus ring to
+   lose. `box-shadow:none` drops the strip's own bottom line with it. */
+.fdy-tabs--vertical .fdy-tabs__list{flex:none;flex-direction:column;width:var(--fdy-tabs-list-w,auto);overflow:visible;box-shadow:none;}
+/* `white-space:normal` and `text-align:start` are corrections, not taste: a tab in a column of
+   fixed width that may not wrap will overflow it, and a button centres its label by default. */
+.fdy-tabs--vertical .fdy-tabs__tab{border-bottom:0;border-radius:var(--radius-md);text-align:start;white-space:normal;}
+.fdy-tabs--vertical .fdy-tabs__tab:focus-visible{border-radius:var(--radius-md);}
+.fdy-tabs--vertical .fdy-tabs__tab[aria-selected="true"],.fdy-tabs--vertical .fdy-tabs__tab[aria-current="page"]{background:var(--color-primary-soft);color:var(--color-primary-strong);font-weight:var(--weight-semibold);}
+.fdy-tabs--vertical .fdy-tabs__panel{flex:1;min-width:0;padding:0;}