@cahyo-dimas/freeday 1.52.1 → 1.54.0

package/adapters/react/components/FdyAppShell.tsx

@@ -0,0 +1,159 @@
+import type { JSX, ReactNode } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+import {
+  NAV_QUERY,
+  applyShellState,
+  focusPanel,
+  restoreFocus,
+  trapTab,
+} from '../../core/app-shell.js';
+
+// A React wrapper over freeday's `.fdy-app` shell (src/components/app-shell.css). React port of
+// adapters/vue/components/FdyAppShell.vue, sharing adapters/core/app-shell.js so the two cannot
+// drift into two different focus traps.
+//
+// ONE model: `navOpen` means "the nav is visible to the reader". Above the nav breakpoint a hidden
+// nav is `--nav-collapsed`, below it a visible nav is `--nav-open` — the kit owns that mapping so an
+// app never reasons about the viewport to answer a question about its own UI.
+//
+// Omit `navOpen` and the component keeps its own, defaulting BY VIEWPORT: a column on a wide screen,
+// hidden on a narrow one. That default is why the prop is optional — a parent cannot express it as a
+// single initial value before it knows the viewport.
+
+export interface FdyAppShellProps {
+  navOpen?: boolean;
+  onNavOpenChange?: (open: boolean) => void;
+  title?: ReactNode;
+  toggleLabel?: string;
+  toggleIcon?: ReactNode;
+  skip?: ReactNode;
+  brand?: ReactNode;
+  nav?: ReactNode;
+  topbar?: ReactNode;
+  children?: ReactNode;
+}
+
+export function FdyAppShell(props: FdyAppShellProps): JSX.Element {
+  const rootRef = useRef<HTMLDivElement>(null);
+  const restoreToRef = useRef<Element | null>(null);
+  /* Set while a viewport change is driving the state, so the effect below reconciles `inert` and
+     the classes but leaves FOCUS alone: a resize is not a reader asking to go somewhere. */
+  const fromResizeRef = useRef<boolean>(false);
+  const [overlay, setOverlay] = useState<boolean>(false);
+  const [uncontrolled, setUncontrolled] = useState<boolean>(true);
+
+  const controlled: boolean = props.navOpen !== undefined;
+  const navVisible: boolean = controlled ? props.navOpen === true : uncontrolled;
+
+  const setVisible = useCallback((next: boolean): void => {
+    if (!controlled) setUncontrolled(next);
+    if (props.onNavOpenChange !== undefined) props.onNavOpenChange(next);
+  }, [controlled, props.onNavOpenChange]);
+
+  /* The media listener reads these through refs and subscribes ONCE. Depending on navVisible would
+     resubscribe on every toggle and re-run the handler, and its "narrowing with the nav visible
+     hides it" rule would then fire on an ordinary open — closing the panel in the same tick the
+     reader opened it. */
+  const navVisibleRef = useRef<boolean>(navVisible);
+  navVisibleRef.current = navVisible;
+  const setVisibleRef = useRef<(next: boolean) => void>(setVisible);
+  setVisibleRef.current = setVisible;
+
+  // The media query owns `overlay`, and the two directions are not symmetrical. Narrowing with the
+  // nav visible would drop an overlay panel over a page nobody asked to leave, so it is hidden;
+  // widening is harmless, since a visible nav simply becomes the column again.
+  useEffect((): (() => void) => {
+    const media: MediaQueryList = window.matchMedia(NAV_QUERY);
+    const onChange = (): void => {
+      const nowOverlay: boolean = !media.matches;
+      setOverlay((was: boolean): boolean => {
+        if (was !== nowOverlay) fromResizeRef.current = true;
+        return nowOverlay;
+      });
+      if (nowOverlay && navVisibleRef.current) setVisibleRef.current(false);
+    };
+    // Mount: adopt the viewport without the hide-on-narrow side effect — nothing is open yet.
+    setOverlay(!media.matches);
+    if (!controlled) setUncontrolled(media.matches);
+    media.addEventListener('change', onChange);
+    return (): void => media.removeEventListener('change', onChange);
+  }, [controlled]);
+
+  // Focus moves only after the class change has been painted, or the panel is still off-canvas and
+  // the browser refuses to focus what it cannot lay out.
+  useEffect((): void => {
+    const el: HTMLDivElement | null = rootRef.current;
+    if (el === null) return;
+    applyShellState(el, { navVisible, overlay });
+    if (fromResizeRef.current) {
+      fromResizeRef.current = false;
+      return;
+    }
+    if (!overlay) return;
+    if (navVisible) restoreToRef.current = focusPanel(el);
+    else restoreFocus(el, restoreToRef.current);
+  }, [navVisible, overlay]);
+
+  useEffect((): (() => void) => {
+    const onKeydown = (e: KeyboardEvent): void => {
+      const el: HTMLDivElement | null = rootRef.current;
+      if (el === null || !overlay || !navVisible) return;
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        setVisible(false);
+        return;
+      }
+      trapTab(el, e);
+    };
+    document.addEventListener('keydown', onKeydown);
+    return (): void => document.removeEventListener('keydown', onKeydown);
+  }, [overlay, navVisible, setVisible]);
+
+  const shellClass: string = overlay
+    ? (navVisible ? 'fdy-app fdy-app--nav-open' : 'fdy-app')
+    : (navVisible ? 'fdy-app' : 'fdy-app fdy-app--nav-collapsed');
+
+  return (
+    <div ref={rootRef} className={shellClass}>
+      {props.skip}
+
+      <aside
+        className="fdy-app__sidebar"
+        onClick={(e): void => {
+          // Following a link in an overlay nav means "take me there" — the panel must not stay over
+          // the page it was just asked for. On a wide viewport the nav is a column: nothing to close.
+          if (!overlay || !navVisible) return;
+          const target: HTMLElement | null = e.target as HTMLElement | null;
+          if (target !== null && target.closest('.fdy-nav__item') !== null) setVisible(false);
+        }}
+      >
+        {props.brand}
+        {props.nav}
+      </aside>
+
+      <div className="fdy-app__content">
+        <header className="fdy-app__topbar">
+          <button
+            className="fdy-app__navtoggle"
+            type="button"
+            aria-label={props.toggleLabel ?? 'Toggle navigation'}
+            onClick={(): void => setVisible(!navVisible)}
+          >{props.toggleIcon ?? '☰'}</button>
+
+          <h1 className="fdy-app__title">{props.title}</h1>
+
+          {props.topbar}
+        </header>
+
+        <main className="fdy-app__main">{props.children}</main>
+      </div>
+
+      <div
+        className="fdy-app__backdrop"
+        onClick={(): void => {
+          if (overlay && navVisible) setVisible(false);
+        }}
+      />
+    </div>
+  );
+}

package/adapters/react/index.d.ts

@@ -41,6 +41,7 @@ export { FdyTable, type FdyTableProps } from './components/FdyTable';
 export { FdyTableFooter, type FdyTableFooterProps } from './components/FdyTableFooter';
 export { FdyModal, type FdyModalProps } from './components/FdyModal';
 export { FdyDrawer, type FdyDrawerProps } from './components/FdyDrawer';
+export { FdyAppShell, type FdyAppShellProps } from './components/FdyAppShell';
 
 /** Controlled data-table types (shared, framework-agnostic core). */
 export type {

package/adapters/react/index.js

@@ -11,3 +11,4 @@ export { FdyTable } from './components/FdyTable.tsx';
 export { FdyTableFooter } from './components/FdyTableFooter.tsx';
 export { FdyModal } from './components/FdyModal.tsx';
 export { FdyDrawer } from './components/FdyDrawer.tsx';
+export { FdyAppShell } from './components/FdyAppShell.tsx';

package/adapters/vue/components/FdyAppShell.vue

@@ -0,0 +1,160 @@
+<script setup lang="ts">
+import { computed, onBeforeUnmount, onMounted, ref, watch, type ComputedRef, type Ref } from 'vue';
+import {
+  NAV_QUERY,
+  applyShellState,
+  focusPanel,
+  restoreFocus,
+  trapTab,
+} from '../../core/app-shell.js';
+
+// A Vue wrapper over freeday's `.fdy-app` shell (src/components/app-shell.css) that ships the
+// behaviour the CSS cannot: Escape, backdrop, focus into the panel and back, `inert`, and a Tab
+// trap. The DOM work lives in adapters/core/app-shell.js so this component, its React twin and the
+// Blazor bridge cannot drift into three different focus traps.
+//
+// ONE model: `navOpen` means "the nav is visible to the reader". The two state classes are the
+// kit's business — above the nav breakpoint a hidden nav is `--nav-collapsed`, below it a visible
+// nav is `--nav-open` — so an app never reasons about the viewport to answer a question about its
+// own UI.
+//
+// Leave `navOpen` unbound and the component keeps its own: visible on a wide viewport, hidden on a
+// narrow one, which is the right default and one an app cannot express in a single initial value.
+// Bind it (`v-model:navOpen`) when the app wants to drive it — a menu item, a persisted preference.
+
+const props = withDefaults(defineProps<{
+  navOpen?: boolean;
+  title?: string;
+  toggleLabel?: string;
+}>(), { navOpen: undefined, title: '', toggleLabel: 'Toggle navigation' });
+
+const emit = defineEmits<{
+  'update:navOpen': [boolean];
+}>();
+
+const root: Ref<HTMLElement | null> = ref(null);
+const overlay: Ref<boolean> = ref(false);
+const uncontrolled: Ref<boolean> = ref(true);
+const restoreTo: Ref<Element | null> = ref(null);
+let media: MediaQueryList | null = null;
+/* Set while a viewport change is driving the state, so the watcher below reconciles `inert` and the
+   classes but leaves FOCUS alone: a resize is not a reader asking to go somewhere. */
+let fromResize: boolean = false;
+
+const navVisible: ComputedRef<boolean> = computed((): boolean =>
+  props.navOpen === undefined ? uncontrolled.value : props.navOpen,
+);
+
+const shellClass: ComputedRef<string> = computed((): string => {
+  if (overlay.value) return navVisible.value ? 'fdy-app fdy-app--nav-open' : 'fdy-app';
+  return navVisible.value ? 'fdy-app' : 'fdy-app fdy-app--nav-collapsed';
+});
+
+function setVisible(next: boolean): void {
+  uncontrolled.value = next;
+  emit('update:navOpen', next);
+}
+
+/* Focus is moved AFTER the class change has been rendered, or the panel is still off-canvas and
+   the browser refuses to focus what it cannot lay out. */
+watch([navVisible, overlay], ([visible, isOverlay]: [boolean, boolean]): void => {
+  const el: HTMLElement | null = root.value;
+  if (el === null) return;
+  applyShellState(el, { navVisible: visible, overlay: isOverlay });
+  if (fromResize) {
+    fromResize = false;
+    return;
+  }
+  if (!isOverlay) return;
+  if (visible) restoreTo.value = focusPanel(el);
+  else restoreFocus(el, restoreTo.value);
+}, { flush: 'post' });
+
+function onToggle(): void {
+  setVisible(!navVisible.value);
+}
+
+function onBackdrop(): void {
+  if (overlay.value && navVisible.value) setVisible(false);
+}
+
+/* Following a link in an overlay nav means "take me there" — the panel must not stay over the page
+   it was just asked for. On a wide viewport the nav is a column and clicking it changes nothing. */
+function onSidebarClick(e: MouseEvent): void {
+  if (!overlay.value || !navVisible.value) return;
+  const target: HTMLElement | null = e.target as HTMLElement | null;
+  if (target !== null && target.closest('.fdy-nav__item') !== null) setVisible(false);
+}
+
+function onKeydown(e: KeyboardEvent): void {
+  const el: HTMLElement | null = root.value;
+  if (el === null || !overlay.value || !navVisible.value) return;
+  if (e.key === 'Escape') {
+    e.preventDefault();
+    setVisible(false);
+    return;
+  }
+  trapTab(el, e);
+}
+
+/* Both directions matter, and they are not symmetrical.
+   Narrowing with the nav visible would drop an overlay panel over a page nobody asked to leave, so
+   the nav is hidden. Widening is harmless — a visible nav simply becomes the column again — and the
+   watcher clears the `inert` the overlay had put on the content. */
+function onMediaChange(): void {
+  const nowOverlay: boolean = media !== null && !media.matches;
+  if (nowOverlay === overlay.value) return;
+  fromResize = true;
+  overlay.value = nowOverlay;
+  if (nowOverlay && navVisible.value) setVisible(false);
+}
+
+onMounted((): void => {
+  media = window.matchMedia(NAV_QUERY);
+  overlay.value = !media.matches;
+  uncontrolled.value = media.matches;
+  media.addEventListener('change', onMediaChange);
+  document.addEventListener('keydown', onKeydown);
+  const el: HTMLElement | null = root.value;
+  if (el !== null) applyShellState(el, { navVisible: navVisible.value, overlay: overlay.value });
+});
+
+onBeforeUnmount((): void => {
+  if (media !== null) media.removeEventListener('change', onMediaChange);
+  document.removeEventListener('keydown', onKeydown);
+});
+</script>
+
+<template>
+  <div ref="root" :class="shellClass">
+    <slot name="skip" />
+
+    <aside class="fdy-app__sidebar" @click="onSidebarClick">
+      <slot name="brand" />
+      <slot name="nav" />
+    </aside>
+
+    <div class="fdy-app__content">
+      <header class="fdy-app__topbar">
+        <button
+          class="fdy-app__navtoggle"
+          type="button"
+          :aria-label="toggleLabel"
+          @click="onToggle"
+        ><slot name="toggle-icon">&#9776;</slot></button>
+
+        <h1 class="fdy-app__title">
+          <slot name="title">{{ title }}</slot>
+        </h1>
+
+        <slot name="topbar" />
+      </header>
+
+      <main class="fdy-app__main">
+        <slot />
+      </main>
+    </div>
+
+    <div class="fdy-app__backdrop" @click="onBackdrop" />
+  </div>
+</template>

package/adapters/vue/index.d.ts

@@ -40,6 +40,7 @@ export { default as FdyTable } from './components/FdyTable.vue';
 export { default as FdyTableFooter } from './components/FdyTableFooter.vue';
 export { default as FdyModal } from './components/FdyModal.vue';
 export { default as FdyDrawer } from './components/FdyDrawer.vue';
+export { default as FdyAppShell } from './components/FdyAppShell.vue';
 
 /** Controlled data-table types (shared, framework-agnostic core). */
 export type {

package/adapters/vue/index.js

@@ -11,3 +11,4 @@ export { default as FdyTable } from './components/FdyTable.vue';
 export { default as FdyTableFooter } from './components/FdyTableFooter.vue';
 export { default as FdyModal } from './components/FdyModal.vue';
 export { default as FdyDrawer } from './components/FdyDrawer.vue';
+export { default as FdyAppShell } from './components/FdyAppShell.vue';

package/dist/freeday-app-shell.js

@@ -0,0 +1,207 @@
+/* Freeday — app shell enhancer (optional, zero-dependency).
+ * Opt in with <div class="fdy-app" data-fdy-app>; the markup is otherwise unchanged.
+ *
+ * The shell has always shipped the state classes and no behaviour, which left every consumer to
+ * assemble the toggle, Escape, focus trap, focus restore and `inert` themselves — and the two
+ * hand-rolled copies in this repo's own docs already disagreed about which of those exist. Below
+ * 721px the sidebar is an OVERLAY (app-shell.css: position:fixed + translateX(-100%)), so it needs
+ * the same treatment a modal drawer gets; at or above 721px it is a column that merely collapses.
+ *
+ * One rule covers both a hidden nav and a hidden page:
+ *   - `__sidebar` is inert whenever the nav is NOT visible. Off-canvas and collapsed panels stay in
+ *     the tab order otherwise — translateX(-100%) and width:0 hide a thing from the eye, not from
+ *     the keyboard, which is how a nav nobody can see still swallows Tab.
+ *   - `__content` is inert only while the nav is an OPEN OVERLAY, so Tab cannot wander behind the
+ *     backdrop.
+ *
+ * Emits a bubbling `fdy-app-nav` CustomEvent (detail {visible}) whenever the nav's visibility
+ * changes, and takes `FreedayAppShell.setVisible(root, visible)` from outside. Those two exist for
+ * the same reason the other enhancers have them: a host that keeps its own state — the Blazor
+ * wrapper binding @bind-NavOpen, an app persisting the collapsed preference — has to be able to
+ * hear the change and to drive it, without owning the behaviour twice.
+ * FreedayAppShell.init(root) for late-mounted markup.
+ */
+(function () {
+  'use strict';
+
+  /* Must match app-shell.css, which switches at (min-width:721px) / (max-width:720px). */
+  var WIDE = '(min-width: 721px)';
+
+  var FOCUSABLE = 'a[href], button:not([disabled]), input:not([disabled]), select:not([disabled]),'
+    + ' textarea:not([disabled]), [tabindex]:not([tabindex="-1"])';
+
+  /* getClientRects(), not offsetParent: an overlay sidebar is position:fixed, and a fixed element
+     reports no offsetParent at all — filtering on it would call every nav item invisible. */
+  function focusables(root) {
+    return Array.prototype.filter.call(root.querySelectorAll(FOCUSABLE), function (el) {
+      return el.getClientRects().length > 0;
+    });
+  }
+
+  function setInert(el, on) {
+    if (!el) return;
+    if (on) el.setAttribute('inert', '');
+    else el.removeAttribute('inert');
+  }
+
+  function initShell(app) {
+    if (app.dataset.fdyAppShellReady === '1') return;
+    app.dataset.fdyAppShellReady = '1';
+
+    var toggle = app.querySelector('.fdy-app__navtoggle');
+    var sidebar = app.querySelector('.fdy-app__sidebar');
+    if (!toggle || !sidebar) return;
+    var content = app.querySelector('.fdy-app__content');
+    var backdrop = app.querySelector('.fdy-app__backdrop');
+
+    var mqWide = window.matchMedia(WIDE);
+    var restoreTo = null;
+    var lastVisible = null;
+
+    function isOverlayOpen() { return app.classList.contains('fdy-app--nav-open'); }
+    function isCollapsed() { return app.classList.contains('fdy-app--nav-collapsed'); }
+    function navVisible() { return mqWide.matches ? !isCollapsed() : isOverlayOpen(); }
+
+    /* aria-expanded answers "is the nav showing?" in BOTH modes — the two state classes are the
+       kit's business, not the reader's. */
+    function sync() {
+      var visible = navVisible();
+      toggle.setAttribute('aria-expanded', String(visible));
+      setInert(sidebar, !visible);
+      setInert(content, !mqWide.matches && visible);
+      /* Announce only real changes. The first sync() runs at init to describe the state the markup
+         arrived in, which is not something a host asked for and must not look like one. */
+      if (lastVisible !== null && visible !== lastVisible) {
+        app.dispatchEvent(new CustomEvent('fdy-app-nav', { bubbles: true, detail: { visible: visible } }));
+      }
+      lastVisible = visible;
+    }
+
+    function open() {
+      if (isOverlayOpen()) return;
+      restoreTo = document.activeElement;
+      app.classList.add('fdy-app--nav-open');
+      sync();
+      var first = focusables(sidebar)[0];
+      if (first) {
+        first.focus();
+      } else {
+        sidebar.setAttribute('tabindex', '-1');
+        sidebar.focus();
+      }
+    }
+
+    /* restoreFocus is false when the viewport closed it rather than the user — a resize must not
+       yank focus out from under whatever the reader was doing. */
+    function close(restoreFocus) {
+      if (!isOverlayOpen()) return;
+      app.classList.remove('fdy-app--nav-open');
+      sync();
+      if (restoreFocus === false) return;
+      /* Back to the control that opened it. document.body is where a keyboard user gets stranded,
+         so anything that is gone, detached or the body itself falls back to the toggle. */
+      var target = (restoreTo && restoreTo !== document.body && document.contains(restoreTo))
+        ? restoreTo : toggle;
+      if (typeof target.focus === 'function') target.focus();
+    }
+
+    toggle.addEventListener('click', function () {
+      if (mqWide.matches) {
+        app.classList.toggle('fdy-app--nav-collapsed');
+        sync();
+      } else if (isOverlayOpen()) {
+        close();
+      } else {
+        open();
+      }
+    });
+
+    if (backdrop) backdrop.addEventListener('click', function () { close(); });
+
+    /* Following a link inside an overlay nav means "take me there" — leaving the panel open over
+       the page you just asked for is the one thing every hand-rolled copy in this repo disagreed on. */
+    sidebar.addEventListener('click', function (e) {
+      if (!isOverlayOpen()) return;
+      if (e.target.closest && e.target.closest('.fdy-nav__item')) close();
+    });
+
+    document.addEventListener('keydown', function (e) {
+      if (!isOverlayOpen()) return;
+      if (e.key === 'Escape') {
+        e.preventDefault();
+        close();
+        return;
+      }
+      if (e.key !== 'Tab') return;
+      /* The trap. `inert` on the content stops Tab reaching the page, but without this the focus
+         would walk out of the document into the browser's own chrome instead of cycling. */
+      var items = focusables(sidebar);
+      if (items.length === 0) {
+        e.preventDefault();
+        return;
+      }
+      var first = items[0], last = items[items.length - 1];
+      if (e.shiftKey && document.activeElement === first) {
+        e.preventDefault();
+        last.focus();
+      } else if (!e.shiftKey && document.activeElement === last) {
+        e.preventDefault();
+        first.focus();
+      }
+    });
+
+    /* Crossing the breakpoint with the overlay open would otherwise leave --nav-open set and the
+       content inert forever: the panel becomes a static column again, and the page it is covering
+       can no longer be clicked or read. */
+    mqWide.addEventListener('change', function () {
+      if (mqWide.matches && isOverlayOpen()) close(false);
+      else sync();
+    });
+
+    sync();
+
+    /* The same handle the other enhancers expose (`_fdyCombo` and friends): a host that binds its
+       own state needs to drive this without reaching for the class names the kit reserves. */
+    app._fdyAppShell = {
+      isVisible: navVisible,
+      setVisible: function (visible) {
+        if (visible === navVisible()) return;
+        if (mqWide.matches) {
+          app.classList.toggle('fdy-app--nav-collapsed', !visible);
+          sync();
+        } else if (visible) {
+          open();
+        } else {
+          close();
+        }
+      },
+    };
+  }
+
+  function initShells(context) {
+    var ctx = context || document;
+    /* root included: querySelectorAll never matches its own root, and a framework ref often sits ON
+       the widget. */
+    if (ctx.matches && ctx.matches('[data-fdy-app]')) initShell(ctx);
+    Array.prototype.forEach.call(ctx.querySelectorAll('[data-fdy-app]'), initShell);
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', function () { initShells(); });
+  } else {
+    initShells();
+  }
+
+  window.FreedayAppShell = {
+    init: initShells,
+    initAll: initShells,
+    /* Both take the shell root. A missing or un-initialised root is a no-op rather than a throw:
+       a host may race the enhancer on first render, and a crash there is worse than a late sync. */
+    setVisible: function (root, visible) {
+      if (root && root._fdyAppShell) root._fdyAppShell.setVisible(visible === true);
+    },
+    isVisible: function (root) {
+      return !!(root && root._fdyAppShell && root._fdyAppShell.isVisible());
+    },
+  };
+})();