@vectoriox/iox-ui 5.64.0 → 5.65.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "5.64.0",
+  "version": "5.65.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",

package/src/actions-core/dialog-motion.ts

@@ -0,0 +1,104 @@
+/**
+ * How a dialog LEAVES (CC1 follow-up — the drawer that vanished). Opening is pure CSS (`@starting-style`
+ * in the shared `iox-design.css`); closing needs one beat of script, because `dialog.close()` drops the
+ * top layer at once and only some browsers can hold it for a transition (`overlay … allow-discrete`).
+ *
+ * The ONE exit every renderer runs: mark the element closing (`data-iox-closing` — the shared CSS gives it
+ * its closed look: the drawer back off its edge, the scrim clear), wait for the transitions that started,
+ * then finish. Reduced motion (or a stub with no animations) finishes now. Framework-free: the engine's
+ * every close path (actions, the X, the backdrop, Esc, the close-above watcher) and the builder canvas's
+ * stage share it.
+ */
+
+export const DIALOG_CLOSING_ATTRIBUTE = 'data-iox-closing';
+
+/** Longest an exit may hold the element before it finishes anyway — a transition that never ends (a
+ *  value that did not change, a tab in the background) must not leave a dialog half-closed. */
+export const DIALOG_EXIT_TIMEOUT_MS = 700;
+
+export interface ExitAnimationLike {
+    finished: Promise<unknown>;
+    effect?: { getComputedTiming?: () => { endTime?: number | null } } | null;
+}
+
+export interface ExitMotionElement {
+    setAttribute(name: string, value: string): void;
+    removeAttribute(name: string): void;
+    hasAttribute(name: string): boolean;
+    getAnimations?: (options?: { subtree?: boolean }) => ExitAnimationLike[];
+}
+
+export interface DialogElementLike extends ExitMotionElement {
+    open: boolean;
+    close(): void;
+}
+
+export interface ExitMotionOptions {
+    /** False under reduced motion: finish at once (the caller asks `motionAllowed()`). */
+    animate: boolean;
+    timeoutMs?: number;
+}
+
+/** True while an exit is running on the element (a second close waits on it; an open cancels it). */
+export function isExiting(el: ExitMotionElement | null | undefined): boolean {
+    return !!el?.hasAttribute(DIALOG_CLOSING_ATTRIBUTE);
+}
+
+/** Stop an exit that is running (the dialog was opened again mid-close): it stays open. */
+export function cancelExit(el: ExitMotionElement | null | undefined): void {
+    el?.removeAttribute(DIALOG_CLOSING_ATTRIBUTE);
+}
+
+const finite = (a: ExitAnimationLike) => {
+    const end = a.effect?.getComputedTiming?.().endTime;
+    return end === undefined || end === null || Number.isFinite(end);
+};
+
+/**
+ * Run the exit: mark the element, wait for its finite animations (its subtree's too — the drawer's links,
+ * the `::backdrop`) or the timeout. Resolves TRUE when the exit completed and the caller should finish
+ * (close / remove), FALSE when it was cancelled meanwhile. The mark stays on until the caller finishes.
+ */
+export async function runExitMotion(el: ExitMotionElement, options: ExitMotionOptions): Promise<boolean> {
+    el.setAttribute(DIALOG_CLOSING_ATTRIBUTE, '');
+    if (!options.animate) return true;
+    // Reading the animations flushes style, so the transitions the mark just started are in the list.
+    const running = (el.getAnimations?.({ subtree: true }) ?? []).filter(finite);
+    if (running.length) {
+        const timeout = options.timeoutMs ?? DIALOG_EXIT_TIMEOUT_MS;
+        let timer: ReturnType<typeof setTimeout> | undefined;
+        await Promise.race([
+            Promise.all(running.map(a => a.finished.catch(() => undefined))),
+            new Promise<void>(resolve => { timer = setTimeout(resolve, timeout); }),
+        ]);
+        if (timer !== undefined) clearTimeout(timer);
+    }
+    return isExiting(el);
+}
+
+const pending = new WeakMap<object, Promise<void>>();
+
+/**
+ * Close a live `<dialog>` with its exit motion. A second call while it is closing joins the first; an open
+ * in between (`cancelExit`) keeps it open. The dialog's own `close` event still fires once, after the
+ * motion — so whatever a runtime does on close (restart the page scroll, sync the openers, return focus)
+ * happens when the dialog is really gone.
+ */
+export function closeDialogAnimated(el: DialogElementLike, options: ExitMotionOptions): Promise<void> {
+    if (!el.open) return Promise.resolve();
+    const running = pending.get(el);
+    if (running && isExiting(el)) return running;
+    const done = runExitMotion(el, options).then(finish => {
+        pending.delete(el);
+        if (!finish) return;
+        if (el.open) el.close();
+        cancelExit(el);
+    });
+    pending.set(el, done);
+    return done;
+}
+
+/** True when a toggle should CLOSE the dialog: it is open and not already on its way out. */
+export function dialogTogglesClosed(el: Pick<DialogElementLike, 'open' | 'hasAttribute'>): boolean {
+    return el.open && !el.hasAttribute(DIALOG_CLOSING_ATTRIBUTE);
+}

package/src/actions-core/public-api.ts

@@ -12,3 +12,4 @@ export * from './action.model';
 export * from './availability';
 export * from './element-actions';
 export * from './dialog-opener';
+export * from './dialog-motion';

package/src/generation-core/nav-shape.ts

@@ -252,8 +252,18 @@ function makeKit(globals: ReadonlyArray<SerializedNode>, rootId: string, newId?:
 
 /** Point an opener's dialog actions at `dialogId` (a drawer rebuilt under a new id keeps its openers working). */
 function retarget(node: SerializedNode, dialogId: string): SerializedNode {
-    for (const ix of node.interactions as Array<{ actions?: Array<{ type?: string; target?: string }> }>) {
-        for (const a of ix.actions ?? []) if (a.type === 'openDialog' || a.type === 'toggleDialog') a.target = dialogId;
+    for (const ix of (node.interactions ?? []) as Array<{ actions?: Array<{ type?: string; target?: string }> }>) {
+        for (const a of ix.actions ?? []) if (a.type === NavDialogAction.Open || a.type === NavDialogAction.Toggle) a.target = dialogId;
+    }
+    return asToggle(node);
+}
+
+/** The menu button and More are TOGGLES (a second click closes what the first opened): a part saved before that
+ *  rule opened only — kept through a change of shape, it toggles from then on. */
+function asToggle(node: SerializedNode): SerializedNode {
+    for (const ix of (node.interactions ?? []) as Array<{ trigger?: string; actions?: Array<{ type?: string }> }>) {
+        if (ix.trigger !== CLICK) continue;
+        for (const a of ix.actions ?? []) if (a.type === NavDialogAction.Open) a.type = NavDialogAction.Toggle;
     }
     return node;
 }
@@ -267,7 +277,14 @@ function part(kit: Kit, suffix: string, type: string, props: Record<string, unkn
     return node;
 }
 
-function clickTo(kit: Kit, suffix: string, type: 'openDialog' | 'closeDialog', target: string) {
+/** The dialog actions a nav part runs on click. */
+enum NavDialogAction {
+    Open = 'openDialog',
+    Close = 'closeDialog',
+    Toggle = 'toggleDialog',
+}
+
+function clickTo(kit: Kit, suffix: string, type: NavDialogAction, target: string) {
     return { id: kit.id(`${suffix}-click`), trigger: CLICK, actions: [{ type, target, duration: 0, delay: 0, easing: 'ease' }] };
 }
 
@@ -302,11 +319,15 @@ function labelText(kit: Kit, suffix: string, words: string): SerializedNode {
     return part(kit, suffix, TEXT, { content: words, tag: 'span' }, 'button-label');
 }
 
+/** The menu button and the drawer's Close are ONE size — and the shared CSS pads the drawer like the header
+ *  (`.iox-role-nav-drawer` re-declares dialog-pad as nav-pad) — so the Close lands where the menu button is and
+ *  reads as the same button turned into an X. */
+const MENU_BUTTON_LAY = { width: '48px', height: '48px', alignItems: 'center', justifyContent: 'center' };
+
 function menuButton(kit: Kit, drawerId: string, at: string): SerializedNode {
-    const btn = part(kit, 'menu', BUTTON, { tag: 'button', ariaLabel: NAV_SHAPE_COPY.menu }, 'button-ghost', NavRole.MenuButton,
-        { width: '48px', height: '48px', alignItems: 'center', justifyContent: 'center' });
+    const btn = part(kit, 'menu', BUTTON, { tag: 'button', ariaLabel: NAV_SHAPE_COPY.menu }, 'button-ghost', NavRole.MenuButton, { ...MENU_BUTTON_LAY });
     btn.children = [iconNode(kit, 'menu-icon', MENU_ICON)];
-    btn.interactions = [clickTo(kit, 'menu', 'openDialog', drawerId)];
+    btn.interactions = [clickTo(kit, 'menu', NavDialogAction.Toggle, drawerId)];
     phoneOnly(btn, at, 'inline-flex');
     return btn;
 }
@@ -322,10 +343,9 @@ function drawer(kit: Kit, root: SerializedNode, pages: NavPage[], at: string): S
     const brandWords = textOf(find([root], NavRole.Brand) ?? root) || NAV_PART_LABELS[NavRole.Root];
     const head = part(kit, 'drawer-head', CONTAINER, {}, 'box', NavRole.DrawerHead,
         { display: 'flex', justifyContent: 'space-between', alignItems: 'center', gap: '12px' });
-    const close = part(kit, 'drawer-close', BUTTON, { tag: 'button', ariaLabel: NAV_SHAPE_COPY.closeMenu }, 'button-ghost', NavRole.DrawerClose,
-        { width: '44px', height: '44px', alignItems: 'center', justifyContent: 'center' });
+    const close = part(kit, 'drawer-close', BUTTON, { tag: 'button', ariaLabel: NAV_SHAPE_COPY.closeMenu }, 'button-ghost', NavRole.DrawerClose, { ...MENU_BUTTON_LAY });
     close.children = [iconNode(kit, 'drawer-close-icon', CLOSE_ICON)];
-    close.interactions = [clickTo(kit, 'drawer-close', 'closeDialog', dr.id)];
+    close.interactions = [clickTo(kit, 'drawer-close', NavDialogAction.Close, dr.id)];
     head.children = [part(kit, 'drawer-brand', HEADING, { content: brandWords, level: 'h3' }, 'h3'), close];
     const list = part(kit, 'drawer-links', CONTAINER, {}, 'box', NavRole.DrawerLinks,
         { display: 'flex', flexDirection: 'column', gap: '4px' });
@@ -364,7 +384,7 @@ const BAR_ITEM_LAY = {
 function moreItem(kit: Kit, drawerId: string): SerializedNode {
     const more = part(kit, 'bar-more', BUTTON, { tag: 'button' }, 'bottom-bar-item', NavRole.More, BAR_ITEM_LAY);
     more.children = [iconNode(kit, 'bar-more-icon', MORE_ICON), labelText(kit, 'bar-more-label', NAV_SHAPE_COPY.more)];
-    more.interactions = [clickTo(kit, 'bar-more', 'openDialog', drawerId)];
+    more.interactions = [clickTo(kit, 'bar-more', NavDialogAction.Toggle, drawerId)];
     return more;
 }
 
@@ -472,7 +492,7 @@ export function planNavShape(globals: ReadonlyArray<SerializedNode>, shape: NavS
 
     // The menu button: Drawer only (Q4: with a bar, the phone header keeps only the brand).
     const existingMenu = removeRole(root, NavRole.MenuButton);
-    const menu = wantMenuButton ? (existingMenu ?? menuButton(kit, dr!.id, at)) : null;
+    const menu = wantMenuButton ? (existingMenu ? asToggle(existingMenu) : menuButton(kit, dr!.id, at)) : null;
 
     for (const p of phoneHiddenParts(root)) { moveDisplayOverride(p, at); hideAt(p, at); }
     centerBrandAt(root, at, wantBar);

package/styles/iox-design.css

@@ -118,15 +118,17 @@ iox-gallery.iox-es-media[data-iox-empty] > .iox-gallery {
 
 /* The DRAWER (board 1, board-8 Q9): a Dialog wearing an element style, placed at the start or end edge, is
    a full-height sheet on that edge — 100dvh (never 100vh: Safari's toolbar), no gap to the edge, the
-   radius kept on its LEADING edge only (a placement rule, not a token). It slides in over dur-base, which
-   the reduced-motion token block sets to 0ms: under reduced motion it simply appears. Beats the engine's
-   placement margins (0,2,1) and the node rule; a Dialog saved before element styles keeps its look. */
+   radius kept on its LEADING edge only (a placement rule, not a token). Beats the engine's placement
+   margins (0,2,1) and the node rule; a Dialog saved before element styles keeps its look. */
 dialog[data-iox-dialog].iox-es:is([data-iox-dialog-placement='end'], [data-iox-dialog-placement='start']) {
     margin-block: 0;
     height: 100dvh;
     max-height: 100dvh;
-    transition: translate var(--iox-dur-base) var(--iox-ease-standard), overlay var(--iox-dur-base) allow-discrete, display var(--iox-dur-base) allow-discrete;
 }
+/* A NAVIGATION's drawer is padded like the header it opens from, so its Close (the menu button's size,
+   generation-core nav-shape) lands where the menu button is — the same button, turned into an X. The token is
+   re-declared, not the padding overridden: a padding the author sets on the drawer still wins. */
+.iox-es.iox-role-nav-drawer { --iox-dialog-pad: var(--iox-nav-pad); }
 dialog[data-iox-dialog].iox-es[data-iox-dialog-placement='end'] {
     margin-inline: auto 0;
     border-start-end-radius: 0;
@@ -137,11 +139,68 @@ dialog[data-iox-dialog].iox-es[data-iox-dialog-placement='start'] {
     border-start-start-radius: 0;
     border-end-start-radius: 0;
 }
+/* How a styled dialog COMES and GOES (CC1 follow-up). Three states, one look each:
+   · at rest, open — in place, the scrim on;
+   · entering (`@starting-style`) and leaving (`data-iox-closing`, set by actions-core `closeDialogAnimated`
+     for the whole exit, and `:not([open])` for a browser that closes it natively) — the drawer off its edge,
+     any other placement faded 12px toward where it sits, the scrim clear.
+   Entering decelerates (ease-enter), leaving accelerates (ease-exit), both over dur-base — the look's motion
+   tokens, which the reduced-motion token block collapses to 0ms: under reduced motion it simply appears and
+   goes. `overlay`/`display` allow-discrete keep a natively closed dialog in the top layer for its exit. */
+dialog[data-iox-dialog].iox-es {
+    --dialog-exit-x: 0px;
+    --dialog-exit-y: 12px;
+    --dialog-exit-opacity: 0;
+    transition:
+        translate var(--iox-dur-base) var(--iox-ease-enter),
+        opacity var(--iox-dur-base) var(--iox-ease-enter),
+        overlay var(--iox-dur-base) allow-discrete,
+        display var(--iox-dur-base) allow-discrete;
+}
+dialog[data-iox-dialog].iox-es[data-iox-dialog-placement='top'] { --dialog-exit-y: -12px; }
+dialog[data-iox-dialog].iox-es:is([data-iox-dialog-placement='end'], [data-iox-dialog-placement='start']) {
+    --dialog-exit-x: 100%;
+    --dialog-exit-y: 0px;
+    --dialog-exit-opacity: 1;
+}
+dialog[data-iox-dialog].iox-es[data-iox-dialog-placement='start'],
+[dir='rtl'] dialog[data-iox-dialog].iox-es[data-iox-dialog-placement='end'] { --dialog-exit-x: -100%; }
+[dir='rtl'] dialog[data-iox-dialog].iox-es[data-iox-dialog-placement='start'] { --dialog-exit-x: 100%; }
+dialog[data-iox-dialog].iox-es:is([data-iox-closing], :not([open])) {
+    translate: var(--dialog-exit-x) var(--dialog-exit-y);
+    opacity: var(--dialog-exit-opacity);
+    transition-timing-function: var(--iox-ease-exit);
+}
+@starting-style {
+    dialog[data-iox-dialog].iox-es[open] {
+        translate: var(--dialog-exit-x) var(--dialog-exit-y);
+        opacity: var(--dialog-exit-opacity);
+    }
+}
+dialog[data-iox-dialog].iox-es::backdrop {
+    transition:
+        opacity var(--iox-dur-base) var(--iox-ease-enter),
+        overlay var(--iox-dur-base) allow-discrete,
+        display var(--iox-dur-base) allow-discrete;
+}
+dialog[data-iox-dialog].iox-es:is([data-iox-closing], :not([open]))::backdrop {
+    opacity: 0;
+    transition-timing-function: var(--iox-ease-exit);
+}
 @starting-style {
-    dialog[data-iox-dialog].iox-es[data-iox-dialog-placement='end'][open] { translate: 100% 0; }
-    dialog[data-iox-dialog].iox-es[data-iox-dialog-placement='start'][open] { translate: -100% 0; }
-    [dir='rtl'] dialog[data-iox-dialog].iox-es[data-iox-dialog-placement='end'][open] { translate: -100% 0; }
-    [dir='rtl'] dialog[data-iox-dialog].iox-es[data-iox-dialog-placement='start'][open] { translate: 100% 0; }
+    dialog[data-iox-dialog].iox-es[open]::backdrop { opacity: 0; }
+}
+/* The drawer's pages follow it in, a beat apart (board 1) — a quarter of dur-fast per link, so they collapse
+   with the tokens under reduced motion. They leave with the sheet, not one by one. */
+dialog[data-iox-dialog].iox-es[open]:not([data-iox-closing]) .iox-role-nav-drawer-links > * {
+    animation: iox-drawer-link-in var(--iox-dur-base) var(--iox-ease-enter) both;
+}
+dialog[data-iox-dialog].iox-es[open] .iox-role-nav-drawer-links > :nth-child(2) { animation-delay: calc(var(--iox-dur-fast) * 0.25); }
+dialog[data-iox-dialog].iox-es[open] .iox-role-nav-drawer-links > :nth-child(3) { animation-delay: calc(var(--iox-dur-fast) * 0.5); }
+dialog[data-iox-dialog].iox-es[open] .iox-role-nav-drawer-links > :nth-child(4) { animation-delay: calc(var(--iox-dur-fast) * 0.75); }
+dialog[data-iox-dialog].iox-es[open] .iox-role-nav-drawer-links > :nth-child(n + 5) { animation-delay: var(--iox-dur-fast); }
+@keyframes iox-drawer-link-in {
+    from { opacity: 0; translate: 0 8px; }
 }
 
 /* A navigation's link lists (board 1): no underline at rest — the current page's link is the one