@flipdish/ui-library 0.28.0 → 0.30.0

package/dist/components/templates/AppShell/index.d.ts

@@ -0,0 +1,40 @@
+import type { ReactNode, Ref } from 'react';
+export interface AppShellScrollAreaProps {
+    /** `id` for the scrolling element, e.g. for a scroll-to-top helper that looks it up. */
+    id?: string;
+    /** Ref to the scrolling element, e.g. to reset `scrollTop` on navigation or attach a scroll listener. */
+    ref?: Ref<HTMLDivElement>;
+    /** Overrides the scrolling element's `data-testid` (defaults to `<root>--scroll-area`). */
+    'data-testid'?: string;
+}
+export interface AppShellProps {
+    /** Primary navigation, rendered first beside the content column. Compose `<SidebarNavigation>` here. */
+    sidebar?: ReactNode;
+    /** Top bar, rendered at the top of the content column. It stays in place while the page area scrolls. Compose `<ApplicationHeader>` here. */
+    header?: ReactNode;
+    /**
+     * Side panel rendered under the header, beside the page area, which narrows to make room. It fills
+     * the height under the header and stays in view while the page area scrolls.
+     */
+    panel?: ReactNode;
+    /** Page content, normally a `<PageLayout>`. Rendered inside the shell's scroll area. */
+    children: ReactNode;
+    /** Hooks for the element that scrolls the page content, since the document itself does not scroll. */
+    scrollAreaProps?: AppShellScrollAreaProps;
+    /** Extra classes merged onto the root element. */
+    className?: string;
+    /** Overrides the `data-testid` (defaults to `fd-app-shell`). */
+    'data-testid'?: string;
+}
+/**
+ * Layout-only template for an app shell: navigation beside a content column that stacks the
+ * header above the page, with an optional side panel that pushes the page instead of covering it.
+ * The shell is exactly the height of the window and the document never scrolls: the page content
+ * scrolls in its own area under the header, so the header, navigation and side panel stay in place
+ * with no sticky positioning. It holds no state and renders whatever is passed to its slots, so the
+ * app keeps ownership of navigation, search and panel state.
+ *
+ * @summary window-height layout template placing navigation, header, a scrolling page area and a side panel
+ */
+export declare const AppShell: ({ sidebar, header, panel, children, scrollAreaProps, className, "data-testid": dataTestId }: AppShellProps) => ReactNode;
+//# sourceMappingURL=index.d.ts.map

package/dist/components/templates/AppShell/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/components/templates/AppShell/index.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,OAAO,CAAC;AAE5C,MAAM,WAAW,uBAAuB;IACtC,wFAAwF;IACxF,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,yGAAyG;IACzG,GAAG,CAAC,EAAE,GAAG,CAAC,cAAc,CAAC,CAAC;IAC1B,2FAA2F;IAC3F,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,MAAM,WAAW,aAAa;IAC5B,wGAAwG;IACxG,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB,6IAA6I;IAC7I,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB,wFAAwF;IACxF,QAAQ,EAAE,SAAS,CAAC;IACpB,sGAAsG;IACtG,eAAe,CAAC,EAAE,uBAAuB,CAAC;IAC1C,kDAAkD;IAClD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gEAAgE;IAChE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,QAAQ,GAAI,6FAA6F,aAAa,KAAG,SA8BrI,CAAC"}

package/dist/components/templates/AppShell/index.js

@@ -0,0 +1,26 @@
+import { jsxs, jsx } from 'react/jsx-runtime';
+import { cx } from '@flipdish/ui-library/utilities/cx';
+import { useResolvedTestId, joinTestId } from '@flipdish/ui-library/utilities/testIdUtils';
+
+/**
+ * Layout-only template for an app shell: navigation beside a content column that stacks the
+ * header above the page, with an optional side panel that pushes the page instead of covering it.
+ * The shell is exactly the height of the window and the document never scrolls: the page content
+ * scrolls in its own area under the header, so the header, navigation and side panel stay in place
+ * with no sticky positioning. It holds no state and renders whatever is passed to its slots, so the
+ * app keeps ownership of navigation, search and panel state.
+ *
+ * @summary window-height layout template placing navigation, header, a scrolling page area and a side panel
+ */
+const AppShell = ({ sidebar, header, panel, children, scrollAreaProps, className, 'data-testid': dataTestId }) => {
+    const appShellTestId = useResolvedTestId({ testId: dataTestId, segment: 'app-shell', rootName: 'app-shell' });
+    return (
+    // A column below `lg`, so a navigation that renders its own mobile top bar stacks above the content.
+    jsxs("div", { "data-testid": appShellTestId, className: cx('flex h-dvh w-full flex-col overflow-hidden bg-primary lg:flex-row', className), children: [sidebar, jsxs("div", { className: "flex min-h-0 min-w-0 flex-1 flex-col", children: [header, jsxs("div", { className: "flex min-h-0 flex-1", children: [jsx("div", { id: scrollAreaProps?.id, ref: scrollAreaProps?.ref, "data-testid": scrollAreaProps?.['data-testid'] ?? joinTestId(appShellTestId, 'scroll-area'), 
+                                // Focusable so keyboard users can scroll a page that has no focusable content of its own (axe: scrollable-region-focusable).
+                                // biome-ignore lint/a11y/noNoninteractiveTabindex: a scrollable region must be reachable by keyboard
+                                tabIndex: 0, className: "flex min-w-0 flex-1 flex-col overflow-y-auto outline-focus-ring focus-visible:outline-2 focus-visible:-outline-offset-2", children: children }), panel] })] })] }));
+};
+
+export { AppShell };
+//# sourceMappingURL=index.js.map

package/dist/components/templates/AppShell/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../../src/components/templates/AppShell/index.tsx"],"sourcesContent":[null],"names":["_jsxs","_jsx"],"mappings":";;;;AAmCA;;;;;;;;;AASG;MACU,QAAQ,GAAG,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,QAAQ,EAAE,eAAe,EAAE,SAAS,EAAE,aAAa,EAAE,UAAU,EAAiB,KAAe;AAChJ,IAAA,MAAM,cAAc,GAAG,iBAAiB,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,OAAO,EAAE,WAAW,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;IAE7G;;IAEEA,IAAA,CAAA,KAAA,EAAA,EAAA,aAAA,EAAkB,cAAc,EAAE,SAAS,EAAE,EAAE,CAAC,mEAAmE,EAAE,SAAS,CAAC,EAAA,QAAA,EAAA,CAC5H,OAAO,EAGRA,IAAA,CAAA,KAAA,EAAA,EAAK,SAAS,EAAC,sCAAsC,aAClD,MAAM,EAEPA,IAAA,CAAA,KAAA,EAAA,EAAK,SAAS,EAAC,qBAAqB,aAClCC,GAAA,CAAA,KAAA,EAAA,EACE,EAAE,EAAE,eAAe,EAAE,EAAE,EACvB,GAAG,EAAE,eAAe,EAAE,GAAG,iBACZ,eAAe,GAAG,aAAa,CAAC,IAAI,UAAU,CAAC,cAAc,EAAE,aAAa,CAAC;;;AAG1F,gCAAA,QAAQ,EAAE,CAAC,EACX,SAAS,EAAC,yHAAyH,EAAA,QAAA,EAElI,QAAQ,EAAA,CACL,EAEL,KAAK,CAAA,EAAA,CACF,CAAA,EAAA,CACF,CAAA,EAAA,CACF;AAEV;;;;"}

package/dist/hooks/__internal__/useHotkeyHint/useHotkeyHint.cjs

@@ -0,0 +1,24 @@
+'use strict';
+
+var usePlatform = require('@flipdish/ui-library/hooks/usePlatform');
+var hotkeys_utils = require('../../../utilities/__internal__/hotkeysUtils/hotkeys.utils.cjs');
+
+/**
+ * Turns a shortcut into the label for the user's device: `mod+k` and `⌘K` both read `⌘K` on macOS and
+ * `Ctrl K` elsewhere. Serves every shortcut label in the library, whether the value is a real hotkey or
+ * display text: text that is not a hotkey (`Hold to talk`) is returned exactly as written. Reads as
+ * the non-Mac form on the server and during hydration.
+ *
+ * @param hotkey `react-hotkeys-hook` syntax (`mod+k`, `mod+slash`, a sequence such as `g>p`), the symbol
+ * shorthand (`⌘K`), a shortcut written out (`Ctrl+K`), or any other text.
+ * @returns The label, or `undefined` when nothing is given.
+ *
+ * @summary format a hotkey as a platform-aware label such as ⌘K or Ctrl K
+ */
+const useHotkeyHint = (hotkey, { commandOn = 'mac' } = {}) => {
+    const { isMac, isApple } = usePlatform.usePlatform();
+    return hotkey ? hotkeys_utils.formatHotkeyLabel(hotkey, commandOn === 'apple' ? isApple : isMac) : undefined;
+};
+
+exports.useHotkeyHint = useHotkeyHint;
+//# sourceMappingURL=useHotkeyHint.cjs.map

package/dist/hooks/__internal__/useHotkeyHint/useHotkeyHint.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHotkeyHint.cjs","sources":["../../../../src/hooks/__internal__/useHotkeyHint/useHotkeyHint.ts"],"sourcesContent":[null],"names":["usePlatform","formatHotkeyLabel"],"mappings":";;;;;AAcA;;;;;;;;;;;AAWG;AACI,MAAM,aAAa,GAAG,CAAC,MAAiC,EAAE,EAAE,SAAS,GAAG,KAAK,EAAA,GAAwB,EAAE,KAAwB;IACpI,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAGA,uBAAW,EAAE;IAExC,OAAO,MAAM,GAAGC,+BAAiB,CAAC,MAAM,EAAE,SAAS,KAAK,OAAO,GAAG,OAAO,GAAG,KAAK,CAAC,GAAG,SAAS;AAChG;;;;"}

package/dist/hooks/__internal__/useHotkeyHint/useHotkeyHint.d.ts

@@ -0,0 +1,22 @@
+export interface HotkeyHintOptions {
+    /**
+     * Which devices press ⌘ for `mod`. `mac` matches `react-hotkeys-hook`, which uses ⌘ on macOS only.
+     * `apple` matches editors built on ProseMirror, which also use ⌘ on iPhone and iPad.
+     * @default "mac"
+     */
+    commandOn?: 'mac' | 'apple';
+}
+/**
+ * Turns a shortcut into the label for the user's device: `mod+k` and `⌘K` both read `⌘K` on macOS and
+ * `Ctrl K` elsewhere. Serves every shortcut label in the library, whether the value is a real hotkey or
+ * display text: text that is not a hotkey (`Hold to talk`) is returned exactly as written. Reads as
+ * the non-Mac form on the server and during hydration.
+ *
+ * @param hotkey `react-hotkeys-hook` syntax (`mod+k`, `mod+slash`, a sequence such as `g>p`), the symbol
+ * shorthand (`⌘K`), a shortcut written out (`Ctrl+K`), or any other text.
+ * @returns The label, or `undefined` when nothing is given.
+ *
+ * @summary format a hotkey as a platform-aware label such as ⌘K or Ctrl K
+ */
+export declare const useHotkeyHint: (hotkey: string | null | undefined, { commandOn }?: HotkeyHintOptions) => string | undefined;
+//# sourceMappingURL=useHotkeyHint.d.ts.map

package/dist/hooks/__internal__/useHotkeyHint/useHotkeyHint.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHotkeyHint.d.ts","sourceRoot":"","sources":["../../../../src/hooks/__internal__/useHotkeyHint/useHotkeyHint.ts"],"names":[],"mappings":"AAKA,MAAM,WAAW,iBAAiB;IAChC;;;;OAIG;IACH,SAAS,CAAC,EAAE,KAAK,GAAG,OAAO,CAAC;CAC7B;AAED;;;;;;;;;;;GAWG;AACH,eAAO,MAAM,aAAa,GAAI,QAAQ,MAAM,GAAG,IAAI,GAAG,SAAS,EAAE,gBAAuB,iBAAsB,KAAG,MAAM,GAAG,SAIzH,CAAC"}

package/dist/hooks/__internal__/useHotkeyHint/useHotkeyHint.js

@@ -0,0 +1,22 @@
+import { usePlatform } from '@flipdish/ui-library/hooks/usePlatform';
+import { formatHotkeyLabel } from '../../../utilities/__internal__/hotkeysUtils/hotkeys.utils.js';
+
+/**
+ * Turns a shortcut into the label for the user's device: `mod+k` and `⌘K` both read `⌘K` on macOS and
+ * `Ctrl K` elsewhere. Serves every shortcut label in the library, whether the value is a real hotkey or
+ * display text: text that is not a hotkey (`Hold to talk`) is returned exactly as written. Reads as
+ * the non-Mac form on the server and during hydration.
+ *
+ * @param hotkey `react-hotkeys-hook` syntax (`mod+k`, `mod+slash`, a sequence such as `g>p`), the symbol
+ * shorthand (`⌘K`), a shortcut written out (`Ctrl+K`), or any other text.
+ * @returns The label, or `undefined` when nothing is given.
+ *
+ * @summary format a hotkey as a platform-aware label such as ⌘K or Ctrl K
+ */
+const useHotkeyHint = (hotkey, { commandOn = 'mac' } = {}) => {
+    const { isMac, isApple } = usePlatform();
+    return hotkey ? formatHotkeyLabel(hotkey, commandOn === 'apple' ? isApple : isMac) : undefined;
+};
+
+export { useHotkeyHint };
+//# sourceMappingURL=useHotkeyHint.js.map

package/dist/hooks/__internal__/useHotkeyHint/useHotkeyHint.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHotkeyHint.js","sources":["../../../../src/hooks/__internal__/useHotkeyHint/useHotkeyHint.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAcA;;;;;;;;;;;AAWG;AACI,MAAM,aAAa,GAAG,CAAC,MAAiC,EAAE,EAAE,SAAS,GAAG,KAAK,EAAA,GAAwB,EAAE,KAAwB;IACpI,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,WAAW,EAAE;IAExC,OAAO,MAAM,GAAG,iBAAiB,CAAC,MAAM,EAAE,SAAS,KAAK,OAAO,GAAG,OAAO,GAAG,KAAK,CAAC,GAAG,SAAS;AAChG;;;;"}

package/dist/hooks/__internal__/useKeySequences/useKeySequences.cjs

@@ -0,0 +1,54 @@
+'use strict';
+
+var React = require('react');
+var hotkeys_utils = require('../../../utilities/__internal__/hotkeysUtils/hotkeys.utils.cjs');
+var platform_utils = require('../../../utilities/__internal__/platformUtils/platform.utils.cjs');
+
+/**
+ * Listens for plain-key shortcuts typed anywhere on the page: single keys (`?`) and sequences
+ * (`g` then `p`), including sequences that share a first key, which `react-hotkeys-hook` cannot
+ * tell apart. Keys pressed with ⌘/Ctrl/Alt or Shift plus a letter, or while focus is in a field, are ignored so ordinary
+ * typing and other shortcuts are never hijacked. A sequence must be completed within `timeoutMs`
+ * of its previous key.
+ *
+ * @summary match single-key and multi-key plain shortcuts outside form fields
+ */
+const useKeySequences = (sequences, onMatch, timeoutMs = 1000) => {
+    const latest = React.useRef({ sequences, onMatch });
+    React.useEffect(() => {
+        latest.current = { sequences, onMatch };
+    });
+    const hasSequences = sequences.length > 0;
+    React.useEffect(() => {
+        if (!hasSequences)
+            return;
+        let buffer = [];
+        let lastKeyAt = 0;
+        const onKeyDown = (event) => {
+            // A key name longer than one character (Shift, Enter, ArrowDown) is not a typed character.
+            if (event.defaultPrevented || event.repeat || event.key.length !== 1 || hotkeys_utils.isTypingInField(event))
+                return;
+            // AltGr (reported as Ctrl+Alt on Windows) and Option on Apple keyboards type characters such as `@` or `[` on many layouts.
+            const os = platform_utils.getPlatformOs();
+            const typesCharacter = event.getModifierState('AltGraph') || ((os === 'macos' || os === 'ios') && event.altKey && !event.ctrlKey);
+            if (event.metaKey || ((event.ctrlKey || event.altKey) && !typesCharacter))
+                return;
+            // Shift plus a letter is its own shortcut (`⇧d`), not the letter.
+            if (event.shiftKey && event.key.toLowerCase() !== event.key.toUpperCase())
+                return;
+            const now = Date.now();
+            const result = hotkeys_utils.advanceKeySequence(now - lastKeyAt > timeoutMs ? [] : buffer, event.key.toLowerCase(), latest.current.sequences);
+            buffer = result.buffer;
+            lastKeyAt = now;
+            if (result.matched !== undefined) {
+                event.preventDefault();
+                latest.current.onMatch(result.matched);
+            }
+        };
+        document.addEventListener('keydown', onKeyDown);
+        return () => document.removeEventListener('keydown', onKeyDown);
+    }, [hasSequences, timeoutMs]);
+};
+
+exports.useKeySequences = useKeySequences;
+//# sourceMappingURL=useKeySequences.cjs.map

package/dist/hooks/__internal__/useKeySequences/useKeySequences.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"useKeySequences.cjs","sources":["../../../../src/hooks/__internal__/useKeySequences/useKeySequences.ts"],"sourcesContent":[null],"names":["useRef","useEffect","isTypingInField","getPlatformOs","advanceKeySequence"],"mappings":";;;;;;AAMA;;;;;;;;AAQG;AACI,MAAM,eAAe,GAAG,CAAC,SAAqB,EAAE,OAAgC,EAAE,SAAS,GAAG,IAAI,KAAU;IACjH,MAAM,MAAM,GAAGA,YAAM,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;IAC7CC,eAAS,CAAC,MAAK;QACb,MAAM,CAAC,OAAO,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE;AACzC,IAAA,CAAC,CAAC;AAEF,IAAA,MAAM,YAAY,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC;IAEzCA,eAAS,CAAC,MAAK;AACb,QAAA,IAAI,CAAC,YAAY;YAAE;QAEnB,IAAI,MAAM,GAAa,EAAE;QACzB,IAAI,SAAS,GAAG,CAAC;AAEjB,QAAA,MAAM,SAAS,GAAG,CAAC,KAAoB,KAAI;;AAEzC,YAAA,IAAI,KAAK,CAAC,gBAAgB,IAAI,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,IAAIC,6BAAe,CAAC,KAAK,CAAC;gBAAE;;AAEhG,YAAA,MAAM,EAAE,GAAGC,4BAAa,EAAE;AAC1B,YAAA,MAAM,cAAc,GAAG,KAAK,CAAC,gBAAgB,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,KAAK,OAAO,IAAI,EAAE,KAAK,KAAK,KAAK,KAAK,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;AACjI,YAAA,IAAI,KAAK,CAAC,OAAO,KAAK,CAAC,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,cAAc,CAAC;gBAAE;;AAE3E,YAAA,IAAI,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,KAAK,CAAC,GAAG,CAAC,WAAW,EAAE;gBAAE;AAE3E,YAAA,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;AACtB,YAAA,MAAM,MAAM,GAAGC,gCAAkB,CAAC,GAAG,GAAG,SAAS,GAAG,SAAS,GAAG,EAAE,GAAG,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC;AAC/H,YAAA,MAAM,GAAG,MAAM,CAAC,MAAM;YACtB,SAAS,GAAG,GAAG;AAEf,YAAA,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,EAAE;gBAChC,KAAK,CAAC,cAAc,EAAE;gBACtB,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC;YACxC;AACF,QAAA,CAAC;AAED,QAAA,QAAQ,CAAC,gBAAgB,CAAC,SAAS,EAAE,SAAS,CAAC;QAC/C,OAAO,MAAM,QAAQ,CAAC,mBAAmB,CAAC,SAAS,EAAE,SAAS,CAAC;AACjE,IAAA,CAAC,EAAE,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;AAC/B;;;;"}

package/dist/hooks/__internal__/useKeySequences/useKeySequences.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Listens for plain-key shortcuts typed anywhere on the page: single keys (`?`) and sequences
+ * (`g` then `p`), including sequences that share a first key, which `react-hotkeys-hook` cannot
+ * tell apart. Keys pressed with ⌘/Ctrl/Alt or Shift plus a letter, or while focus is in a field, are ignored so ordinary
+ * typing and other shortcuts are never hijacked. A sequence must be completed within `timeoutMs`
+ * of its previous key.
+ *
+ * @summary match single-key and multi-key plain shortcuts outside form fields
+ */
+export declare const useKeySequences: (sequences: string[][], onMatch: (index: number) => void, timeoutMs?: number) => void;
+//# sourceMappingURL=useKeySequences.d.ts.map

package/dist/hooks/__internal__/useKeySequences/useKeySequences.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useKeySequences.d.ts","sourceRoot":"","sources":["../../../../src/hooks/__internal__/useKeySequences/useKeySequences.ts"],"names":[],"mappings":"AAMA;;;;;;;;GAQG;AACH,eAAO,MAAM,eAAe,GAAI,WAAW,MAAM,EAAE,EAAE,EAAE,SAAS,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,EAAE,kBAAgB,KAAG,IAsC3G,CAAC"}

package/dist/hooks/__internal__/useKeySequences/useKeySequences.js

@@ -0,0 +1,52 @@
+import { useRef, useEffect } from 'react';
+import { isTypingInField, advanceKeySequence } from '../../../utilities/__internal__/hotkeysUtils/hotkeys.utils.js';
+import { getPlatformOs } from '../../../utilities/__internal__/platformUtils/platform.utils.js';
+
+/**
+ * Listens for plain-key shortcuts typed anywhere on the page: single keys (`?`) and sequences
+ * (`g` then `p`), including sequences that share a first key, which `react-hotkeys-hook` cannot
+ * tell apart. Keys pressed with ⌘/Ctrl/Alt or Shift plus a letter, or while focus is in a field, are ignored so ordinary
+ * typing and other shortcuts are never hijacked. A sequence must be completed within `timeoutMs`
+ * of its previous key.
+ *
+ * @summary match single-key and multi-key plain shortcuts outside form fields
+ */
+const useKeySequences = (sequences, onMatch, timeoutMs = 1000) => {
+    const latest = useRef({ sequences, onMatch });
+    useEffect(() => {
+        latest.current = { sequences, onMatch };
+    });
+    const hasSequences = sequences.length > 0;
+    useEffect(() => {
+        if (!hasSequences)
+            return;
+        let buffer = [];
+        let lastKeyAt = 0;
+        const onKeyDown = (event) => {
+            // A key name longer than one character (Shift, Enter, ArrowDown) is not a typed character.
+            if (event.defaultPrevented || event.repeat || event.key.length !== 1 || isTypingInField(event))
+                return;
+            // AltGr (reported as Ctrl+Alt on Windows) and Option on Apple keyboards type characters such as `@` or `[` on many layouts.
+            const os = getPlatformOs();
+            const typesCharacter = event.getModifierState('AltGraph') || ((os === 'macos' || os === 'ios') && event.altKey && !event.ctrlKey);
+            if (event.metaKey || ((event.ctrlKey || event.altKey) && !typesCharacter))
+                return;
+            // Shift plus a letter is its own shortcut (`⇧d`), not the letter.
+            if (event.shiftKey && event.key.toLowerCase() !== event.key.toUpperCase())
+                return;
+            const now = Date.now();
+            const result = advanceKeySequence(now - lastKeyAt > timeoutMs ? [] : buffer, event.key.toLowerCase(), latest.current.sequences);
+            buffer = result.buffer;
+            lastKeyAt = now;
+            if (result.matched !== undefined) {
+                event.preventDefault();
+                latest.current.onMatch(result.matched);
+            }
+        };
+        document.addEventListener('keydown', onKeyDown);
+        return () => document.removeEventListener('keydown', onKeyDown);
+    }, [hasSequences, timeoutMs]);
+};
+
+export { useKeySequences };
+//# sourceMappingURL=useKeySequences.js.map

package/dist/hooks/__internal__/useKeySequences/useKeySequences.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useKeySequences.js","sources":["../../../../src/hooks/__internal__/useKeySequences/useKeySequences.ts"],"sourcesContent":[null],"names":[],"mappings":";;;;AAMA;;;;;;;;AAQG;AACI,MAAM,eAAe,GAAG,CAAC,SAAqB,EAAE,OAAgC,EAAE,SAAS,GAAG,IAAI,KAAU;IACjH,MAAM,MAAM,GAAG,MAAM,CAAC,EAAE,SAAS,EAAE,OAAO,EAAE,CAAC;IAC7C,SAAS,CAAC,MAAK;QACb,MAAM,CAAC,OAAO,GAAG,EAAE,SAAS,EAAE,OAAO,EAAE;AACzC,IAAA,CAAC,CAAC;AAEF,IAAA,MAAM,YAAY,GAAG,SAAS,CAAC,MAAM,GAAG,CAAC;IAEzC,SAAS,CAAC,MAAK;AACb,QAAA,IAAI,CAAC,YAAY;YAAE;QAEnB,IAAI,MAAM,GAAa,EAAE;QACzB,IAAI,SAAS,GAAG,CAAC;AAEjB,QAAA,MAAM,SAAS,GAAG,CAAC,KAAoB,KAAI;;AAEzC,YAAA,IAAI,KAAK,CAAC,gBAAgB,IAAI,KAAK,CAAC,MAAM,IAAI,KAAK,CAAC,GAAG,CAAC,MAAM,KAAK,CAAC,IAAI,eAAe,CAAC,KAAK,CAAC;gBAAE;;AAEhG,YAAA,MAAM,EAAE,GAAG,aAAa,EAAE;AAC1B,YAAA,MAAM,cAAc,GAAG,KAAK,CAAC,gBAAgB,CAAC,UAAU,CAAC,KAAK,CAAC,EAAE,KAAK,OAAO,IAAI,EAAE,KAAK,KAAK,KAAK,KAAK,CAAC,MAAM,IAAI,CAAC,KAAK,CAAC,OAAO,CAAC;AACjI,YAAA,IAAI,KAAK,CAAC,OAAO,KAAK,CAAC,KAAK,CAAC,OAAO,IAAI,KAAK,CAAC,MAAM,KAAK,CAAC,cAAc,CAAC;gBAAE;;AAE3E,YAAA,IAAI,KAAK,CAAC,QAAQ,IAAI,KAAK,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,KAAK,CAAC,GAAG,CAAC,WAAW,EAAE;gBAAE;AAE3E,YAAA,MAAM,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE;AACtB,YAAA,MAAM,MAAM,GAAG,kBAAkB,CAAC,GAAG,GAAG,SAAS,GAAG,SAAS,GAAG,EAAE,GAAG,MAAM,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,EAAE,EAAE,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC;AAC/H,YAAA,MAAM,GAAG,MAAM,CAAC,MAAM;YACtB,SAAS,GAAG,GAAG;AAEf,YAAA,IAAI,MAAM,CAAC,OAAO,KAAK,SAAS,EAAE;gBAChC,KAAK,CAAC,cAAc,EAAE;gBACtB,MAAM,CAAC,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC,OAAO,CAAC;YACxC;AACF,QAAA,CAAC;AAED,QAAA,QAAQ,CAAC,gBAAgB,CAAC,SAAS,EAAE,SAAS,CAAC;QAC/C,OAAO,MAAM,QAAQ,CAAC,mBAAmB,CAAC,SAAS,EAAE,SAAS,CAAC;AACjE,IAAA,CAAC,EAAE,CAAC,YAAY,EAAE,SAAS,CAAC,CAAC;AAC/B;;;;"}

package/dist/hooks/usePlatform/index.cjs

@@ -0,0 +1,22 @@
+'use strict';
+
+var React = require('react');
+var platform_utils = require('../../utilities/__internal__/platformUtils/platform.utils.cjs');
+
+const subscribeToNothing = () => () => { };
+const getServerOs = () => 'unknown';
+/**
+ * Reports the operating system of the user's device, for wording that depends on it: a shortcut
+ * label, a download link, a help article. Detection reads the user agent, so treat it as a best
+ * guess and never as a reason to change behaviour; use `useBreakpoints` or feature detection for
+ * that. Every flag is `false` on the server and during hydration, then settles on the real device.
+ *
+ * @summary detect the user's operating system, safely across hydration
+ */
+const usePlatform = () => {
+    const os = React.useSyncExternalStore(subscribeToNothing, platform_utils.getPlatformOs, getServerOs);
+    return React.useMemo(() => ({ os, isMac: os === 'macos', isApple: os === 'macos' || os === 'ios', isWindows: os === 'windows' }), [os]);
+};
+
+exports.usePlatform = usePlatform;
+//# sourceMappingURL=index.cjs.map

package/dist/hooks/usePlatform/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../../../src/hooks/usePlatform/index.ts"],"sourcesContent":[null],"names":["useSyncExternalStore","getPlatformOs","useMemo"],"mappings":";;;;;AAmBA,MAAM,kBAAkB,GAAG,MAAM,MAAK,EAAE,CAAC;AACzC,MAAM,WAAW,GAAG,MAAkB,SAAS;AAE/C;;;;;;;AAOG;AACI,MAAM,WAAW,GAAG,MAAmB;IAC5C,MAAM,EAAE,GAAGA,0BAAoB,CAAC,kBAAkB,EAAEC,4BAAa,EAAE,WAAW,CAAC;AAE/E,IAAA,OAAOC,aAAO,CAAC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,KAAK,OAAO,EAAE,OAAO,EAAE,EAAE,KAAK,OAAO,IAAI,EAAE,KAAK,KAAK,EAAE,SAAS,EAAE,EAAE,KAAK,SAAS,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;AACnI;;;;"}

package/dist/hooks/usePlatform/index.d.ts

@@ -0,0 +1,22 @@
+import type { PlatformOs } from '../../utilities/__internal__/platformUtils/platform.utils';
+export type { PlatformOs };
+export interface PlatformInfo {
+    /** The operating system, or `unknown` on the server, during hydration and when it cannot be told. */
+    os: PlatformOs;
+    /** macOS only, where ⌘ is the primary shortcut modifier. Also true for an iPad in desktop mode, which reports itself as a Mac. */
+    isMac: boolean;
+    /** Any Apple device: macOS, iPhone or iPad. */
+    isApple: boolean;
+    /** Windows only, where the primary shortcut modifier is `ctrl`. */
+    isWindows: boolean;
+}
+/**
+ * Reports the operating system of the user's device, for wording that depends on it: a shortcut
+ * label, a download link, a help article. Detection reads the user agent, so treat it as a best
+ * guess and never as a reason to change behaviour; use `useBreakpoints` or feature detection for
+ * that. Every flag is `false` on the server and during hydration, then settles on the real device.
+ *
+ * @summary detect the user's operating system, safely across hydration
+ */
+export declare const usePlatform: () => PlatformInfo;
+//# sourceMappingURL=index.d.ts.map

package/dist/hooks/usePlatform/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/hooks/usePlatform/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2DAA2D,CAAC;AAE5F,YAAY,EAAE,UAAU,EAAE,CAAC;AAE3B,MAAM,WAAW,YAAY;IAC3B,qGAAqG;IACrG,EAAE,EAAE,UAAU,CAAC;IACf,kIAAkI;IAClI,KAAK,EAAE,OAAO,CAAC;IACf,+CAA+C;IAC/C,OAAO,EAAE,OAAO,CAAC;IACjB,mEAAmE;IACnE,SAAS,EAAE,OAAO,CAAC;CACpB;AAKD;;;;;;;GAOG;AACH,eAAO,MAAM,WAAW,QAAO,YAI9B,CAAC"}

package/dist/hooks/usePlatform/index.js

@@ -0,0 +1,20 @@
+import { useSyncExternalStore, useMemo } from 'react';
+import { getPlatformOs } from '../../utilities/__internal__/platformUtils/platform.utils.js';
+
+const subscribeToNothing = () => () => { };
+const getServerOs = () => 'unknown';
+/**
+ * Reports the operating system of the user's device, for wording that depends on it: a shortcut
+ * label, a download link, a help article. Detection reads the user agent, so treat it as a best
+ * guess and never as a reason to change behaviour; use `useBreakpoints` or feature detection for
+ * that. Every flag is `false` on the server and during hydration, then settles on the real device.
+ *
+ * @summary detect the user's operating system, safely across hydration
+ */
+const usePlatform = () => {
+    const os = useSyncExternalStore(subscribeToNothing, getPlatformOs, getServerOs);
+    return useMemo(() => ({ os, isMac: os === 'macos', isApple: os === 'macos' || os === 'ios', isWindows: os === 'windows' }), [os]);
+};
+
+export { usePlatform };
+//# sourceMappingURL=index.js.map

package/dist/hooks/usePlatform/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../../../src/hooks/usePlatform/index.ts"],"sourcesContent":[null],"names":[],"mappings":";;;AAmBA,MAAM,kBAAkB,GAAG,MAAM,MAAK,EAAE,CAAC;AACzC,MAAM,WAAW,GAAG,MAAkB,SAAS;AAE/C;;;;;;;AAOG;AACI,MAAM,WAAW,GAAG,MAAmB;IAC5C,MAAM,EAAE,GAAG,oBAAoB,CAAC,kBAAkB,EAAE,aAAa,EAAE,WAAW,CAAC;AAE/E,IAAA,OAAO,OAAO,CAAC,OAAO,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,KAAK,OAAO,EAAE,OAAO,EAAE,EAAE,KAAK,OAAO,IAAI,EAAE,KAAK,KAAK,EAAE,SAAS,EAAE,EAAE,KAAK,SAAS,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;AACnI;;;;"}

package/dist/native/components/templates/AppShell/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `AppShell` has no React Native implementation.
+ *
+ * This is a generated types-only stub (scripts/emit-native-stubs.mjs). It exists so
+ * that importing `@flipdish/ui-library/components/templates/AppShell` from React Native fails at
+ * compile time rather than resolving to the web build's types. There is no
+ * matching `index.js`, so Metro cannot bundle this module either.
+ *
+ * To make `AppShell` available on React Native, add an `index.native.tsx` beside
+ * its `index.tsx` — the build picks it up automatically and this stub disappears.
+ */
+export declare const __NO_REACT_NATIVE_IMPLEMENTATION__: never;

package/dist/native/hooks/usePlatform/index.d.ts

@@ -0,0 +1,12 @@
+/**
+ * `usePlatform` has no React Native implementation.
+ *
+ * This is a generated types-only stub (scripts/emit-native-stubs.mjs). It exists so
+ * that importing `@flipdish/ui-library/hooks/usePlatform` from React Native fails at
+ * compile time rather than resolving to the web build's types. There is no
+ * matching `index.js`, so Metro cannot bundle this module either.
+ *
+ * To make `usePlatform` available on React Native, add an `index.native.tsx` beside
+ * its `index.tsx` — the build picks it up automatically and this stub disappears.
+ */
+export declare const __NO_REACT_NATIVE_IMPLEMENTATION__: never;