@flamingo-stack/openframe-frontend-core 0.0.838 → 0.0.840

package/src/components/navigation/navigation-sidebar.tsx

@@ -1,13 +1,15 @@
 'use client';
 
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
-import type { CSSProperties, MouseEvent, ReactNode } from 'react';
+import type { CSSProperties, MouseEvent, ReactNode, RefObject } from 'react';
 import { useIsHydrated } from '../../hooks/ui/use-is-hydrated';
 import { useIsomorphicLayoutEffect } from '../../hooks/ui/use-isomorphic-layout-effect';
 import { useLocalStorage } from '../../hooks/ui/use-local-storage';
 import { useLgUp, useMdUp } from '../../hooks/ui/use-media-query';
+import { useResizablePanelSize } from '../../hooks/ui/use-resizable-panel-size';
 import type { NavigationSidebarConfig, NavigationSidebarItem } from '../../types/navigation';
 import { cn } from '../../utils';
+import { PanelResizeGrip, PanelResizeHandle } from '../ui/panel-resize-handle';
 import { NAVIGATION_SIDEBAR_ATTRIBUTE } from './app-layout-context';
 import {
   NavigationSidebarGroupedEntries,
@@ -24,6 +26,12 @@ const MINIMIZED_WIDTH = 56; // 3.5rem = 56px
 const EXPANDED_WIDTH = 224; // 14rem = 224px — the default; a grouped config may set its own
 /** The narrowest custom `expandedWidth`: the rows read 140px and up as expanded. */
 const MIN_CUSTOM_EXPANDED_WIDTH = 141;
+/**
+ * Px of its row a resizable sidebar leaves to the content beside it
+ * (`NavigationSidebarResizeConfig.minContentWidth`): the `content-md`
+ * breakpoint, under which page content lays out for a phone.
+ */
+const DEFAULT_MIN_CONTENT_WIDTH = 720;
 const STORAGE_KEY = 'of.navigationSidebar.minimized';
 
 /**
@@ -146,6 +154,27 @@ const SIDEBAR_TABLET_WIDTH = {
   customOverlay: 'md:w-[var(--of-navigation-sidebar-expanded-width)]',
 } as const;
 
+/**
+ * The width of the sidebar's row — its parent, the room it shares with the
+ * content — for the resize clamp. 0 until measured, and when there is nothing to
+ * measure (not resizable, no parent, the server).
+ */
+function useRowWidth(asideRef: RefObject<HTMLElement | null>, enabled: boolean): number {
+  const [width, setWidth] = useState(0);
+  useEffect(() => {
+    const row = enabled ? asideRef.current?.parentElement : null;
+    if (!row) return undefined;
+    const update = () => setWidth(row.clientWidth);
+    update();
+    // An environment without ResizeObserver (jsdom in a consumer's tests) measures once.
+    if (typeof ResizeObserver === 'undefined') return undefined;
+    const observer = new ResizeObserver(update);
+    observer.observe(row);
+    return () => observer.disconnect();
+  }, [asideRef, enabled]);
+  return width;
+}
+
 /** A click the browser will resolve itself — new tab, new window, middle button. */
 export const isModifiedClick = (event?: MouseEvent): boolean =>
   !!event && (event.metaKey || event.ctrlKey || event.shiftKey || event.altKey || event.button !== 0);
@@ -255,18 +284,74 @@ export function NavigationSidebar({
 
   // A grouped config's own expanded width (`expandedWidth`); `null` = the
   // default 224px through the literal classes, exactly as before.
-  const customExpandedWidth =
+  const configExpandedWidth =
     config.variant === 'grouped' && config.expandedWidth !== undefined
       ? Math.max(config.expandedWidth, MIN_CUSTOM_EXPANDED_WIDTH)
       : null;
-  const expandedWidth = customExpandedWidth ?? EXPANDED_WIDTH;
+
+  // `config.resizable`: the expanded width is the user's — dragged or stepped on
+  // the handle below, kept under the config's storage key — and the config width
+  // is where it starts. Clamped to the config's bounds and to the row, so the
+  // content beside the rail keeps `minContentWidth`. Not resizable: the config
+  // width, and the hook reads and writes nothing.
+  const resize = config.resizable;
+  const asideRef = useRef<HTMLElement>(null);
+  const rowWidth = useRowWidth(asideRef, resize !== undefined);
+  const resizeMinWidth = Math.max(resize?.minWidth ?? MIN_CUSTOM_EXPANDED_WIDTH, MIN_CUSTOM_EXPANDED_WIDTH);
+  const {
+    size: chosenExpandedWidth,
+    setSize: setChosenExpandedWidth,
+    resetSize: resetChosenExpandedWidth,
+    clampSize: clampExpandedWidth,
+  } = useResizablePanelSize({
+    enabled: resize !== undefined,
+    minSize: resizeMinWidth,
+    maxSize: resize?.maxWidth ?? Number.POSITIVE_INFINITY,
+    defaultSize: configExpandedWidth ?? EXPANDED_WIDTH,
+    available: rowWidth,
+    reserve: resize?.minContentWidth ?? DEFAULT_MIN_CONTENT_WIDTH,
+    storageKey: resize?.storageKey,
+  });
+
+  // The desktop width — what the effect below publishes. The chosen width may
+  // be used here as soon as it is known: an effect never runs into the SSR HTML.
+  const expandedWidth = resize !== undefined ? chosenExpandedWidth : (configExpandedWidth ?? EXPANDED_WIDTH);
+  // The width in the MARKUP — the inline custom property on the rail and its
+  // tablet slot, which the tablet overlay opens to and the desktop rule falls
+  // back on, and the handle's `aria-valuenow`: the chosen width only once
+  // hydrated. The server could not read it, and a first client render that
+  // differs is a hydration mismatch, which React reports and leaves in the DOM.
+  // Until then the config width stands, as for a sidebar that is not resizable;
+  // on desktop the seeded width shows throughout, so nothing moves.
+  const markupExpandedWidth = hydrated ? chosenExpandedWidth : (configExpandedWidth ?? EXPANDED_WIDTH);
+  const customExpandedWidth = resize !== undefined ? markupExpandedWidth : configExpandedWidth;
   const expandedWidthStyle =
     customExpandedWidth === null ? undefined : ({ [EXPANDED_WIDTH_VAR]: `${customExpandedWidth}px` } as CSSProperties);
 
+  // A drag moves the rail's own width property on every pointer move and marks
+  // the rail (`data-resizing`, read by a class on it) so its width transition
+  // does not trail the pointer; the choice is committed once, on release, which
+  // also lifts the mark. Neither write concerns hydration: both run on the
+  // client only, once the user has the handle.
+  const dragExpandedWidth = useCallback((next: number) => {
+    const aside = asideRef.current;
+    if (!aside) return;
+    aside.setAttribute('data-resizing', '');
+    aside.style.setProperty(NAVIGATION_SIDEBAR_WIDTH_VAR, `${Math.round(next)}px`);
+  }, []);
+  const commitExpandedWidth = useCallback(
+    (next: number) => {
+      asideRef.current?.removeAttribute('data-resizing');
+      setChosenExpandedWidth(next);
+    },
+    [setChosenExpandedWidth],
+  );
+
   // A new expanded width (the host swapped configs — e.g. a placeholder for
-  // the grouped tree) is a different sidebar, not a toggle: it snaps instead of
-  // animating. The transition is dropped in the same commit that moves the
-  // width and comes back a frame later (the effect below).
+  // the grouped tree; a resize committed, stepped or reset on the handle) is a
+  // different sidebar, not a toggle: it snaps instead of animating. The
+  // transition is dropped in the same commit that moves the width and comes
+  // back a frame later (the effect below).
   const [widthFor, setWidthFor] = useState(expandedWidth);
   if (widthFor !== expandedWidth) {
     setWidthFor(expandedWidth);
@@ -447,7 +532,6 @@ export function NavigationSidebar({
   // On the rail, not on `<html>` where the seed sits: the rail is its only reader,
   // and an inherited custom property on the root made WebKit restyle the whole
   // document on every toggle. Its own value overrides the inherited seed.
-  const asideRef = useRef<HTMLElement>(null);
   useIsomorphicLayoutEffect(() => {
     asideRef.current?.style.setProperty(NAVIGATION_SIDEBAR_WIDTH_VAR, sidebarWidth);
   }, [sidebarWidth]);
@@ -555,6 +639,9 @@ export function NavigationSidebar({
               ? SIDEBAR_TABLET_WIDTH.overlay
               : SIDEBAR_TABLET_WIDTH.customOverlay,
           transitionsEnabled && widthTransition,
+          // A drag on the resize handle in progress: the width follows the
+          // pointer, with no transition trailing it (`dragExpandedWidth`).
+          'data-[resizing]:transition-none',
           // Snaps where its width moves the content: the desktop rail, and the
           // tablet overlay too when it pushes (its slot above snaps with it).
           !animateWidth && (pushOnTablet ? 'transition-none' : 'lg:transition-none'),
@@ -632,6 +719,28 @@ export function NavigationSidebar({
           onToggle={handleToggle}
           compact={grouped}
         />
+
+        {/* The resize handle (`config.resizable`), astride the rail's right edge —
+            the grip the Mingo chat drawer had — on desktop while expanded: the
+            56px rail has nothing to resize, and below `lg` the width is the
+            tablet's. The 24px track straddles the border, half of it over the
+            content's edge; the grip marks the border as draggable. */}
+        {resize !== undefined && !minimized && (
+          <PanelResizeHandle
+            side="left"
+            variant="inLayout"
+            size={markupExpandedWidth}
+            minSize={resizeMinWidth}
+            maxSize={clampExpandedWidth(Number.POSITIVE_INFINITY)}
+            clampSize={clampExpandedWidth}
+            onSize={commitExpandedWidth}
+            onDrag={dragExpandedWidth}
+            onReset={resetChosenExpandedWidth}
+            ariaLabel="Resize navigation sidebar"
+            className="inset-y-0 hidden w-6 -translate-x-1/2 justify-center pl-0 lg:flex"
+            grip={<PanelResizeGrip />}
+          />
+        )}
       </aside>
     </>
   );

package/src/components/product-demo/fixtures/software-update.ts

@@ -16,7 +16,7 @@ const chrome: SelectedPackage = {
 const TONIGHT_11_PM = { value: '23:00', label: '11:00 PM' };
 
 /** A fixed reading of the schedule fields: tonight's late slots, nothing in the past. */
-const timing: SoftwareScheduleTiming = {
+export const SOFTWARE_DEMO_TIMING: SoftwareScheduleTiming = {
   timeReferenceOptions: [
     { value: 'SERVER', label: 'Your account timezone' },
     { value: 'DEVICE_LOCAL', label: 'Device local timezone' },
@@ -49,7 +49,7 @@ export function buildSoftwareUpdateFixture(cast: DemoCast) {
   return {
     action: 'UPDATE',
     package: chrome,
-    timing,
+    timing: SOFTWARE_DEMO_TIMING,
     initialValues,
     devices,
     selectedIds: new Set<string>([DEMO_DEVICES.reception.id, DEMO_DEVICES.samT14.id, DEMO_DEVICES.frontDesk.id]),

package/src/components/ui/panel-resize-handle.tsx

@@ -3,13 +3,37 @@
 import { type KeyboardEvent, type PointerEvent, type ReactNode, type RefObject, useEffect, useRef } from 'react';
 
 import { cn } from '../../utils/cn';
+import { Menu01Icon } from '../icons-v2-generated';
 
 /**
- * The drag-to-resize handle of a side or edge panel, shared by `Drawer` and
- * `AppLayoutDrawer`. A drag writes the panel's size to the DOM and reports it
- * once, on release; arrow keys, Home and End report at once.
+ * The drag-to-resize handle of a side or edge panel, shared by `Drawer`,
+ * `AppLayoutDrawer`, `ComposerSheet` and `NavigationSidebar`. A drag writes the
+ * panel's size to the DOM (or hands it to `onDrag`) and reports it once, on
+ * release; arrow keys, Home and End report at once; a double click asks for the
+ * default (`onReset`).
  */
 
+/**
+ * The grip the design draws on a resizable edge (its `resize-handle`): a 16×32
+ * pill in the page's background astride the panel's border, with a three-line
+ * mark. `NavigationSidebar` hands it to the handle as its `grip`, and
+ * `AppLayoutSidePanel`'s own handle draws it too.
+ */
+export function PanelResizeGrip({ className }: { className?: string }) {
+  return (
+    <span
+      aria-hidden
+      className={cn(
+        'flex h-8 w-4 items-center justify-center rounded-sm border border-ods-border bg-ods-bg text-ods-text-secondary transition-colors',
+        'group-hover:border-ods-border-hover group-focus-visible:border-ods-accent group-focus-visible:text-ods-accent',
+        className,
+      )}
+    >
+      <Menu01Icon size={12} />
+    </span>
+  );
+}
+
 type PanelSide = 'right' | 'left' | 'top' | 'bottom';
 
 const HORIZONTAL_SIDES: ReadonlySet<PanelSide> = new Set(['left', 'right']);
@@ -37,8 +61,18 @@ export interface PanelResizeHandleProps {
   onSize: (next: number) => void;
   /** Clamp a candidate size to the min/max and the container. */
   clampSize: (next: number) => number;
-  /** The panel the size applies to — written directly while dragging. */
-  panelRef: RefObject<HTMLDivElement | null>;
+  /** The panel the size applies to — written directly while dragging. Omit for a
+   *  panel sized by other means (`onDrag`). */
+  panelRef?: RefObject<HTMLDivElement | null>;
+  /**
+   * Every size the drag reaches, in place of writing `panelRef`'s inline size:
+   * for a panel whose width is a custom property or a class rather than an
+   * inline style, or one that marks itself while dragged. `onSize` still
+   * reports once, on release.
+   */
+  onDrag?: (next: number) => void;
+  /** A double click on the handle: back to the default size. */
+  onReset?: () => void;
   /** `overlay` is the body-level `Drawer`'s handle, `inLayout` the wider one of
    *  `AppLayoutDrawer`. They differ in track width and grip colour only. */
   variant: 'overlay' | 'inLayout';
@@ -57,6 +91,8 @@ export function PanelResizeHandle({
   onSize,
   clampSize,
   panelRef,
+  onDrag,
+  onReset,
   variant,
   ariaLabel,
   className,
@@ -95,12 +131,17 @@ export function PanelResizeHandle({
   // the size is unchanged, so it leaves the style alone.
   const handlePointerMove = (e: PointerEvent<HTMLDivElement>) => {
     const start = startRef.current;
-    const panel = panelRef.current;
-    if (!start || !panel) return;
+    if (!start) return;
+    if (!onDrag && !panelRef?.current) return;
     const delta = isHorizontal ? e.clientX - start.x : e.clientY - start.y;
     const next = clampSize(start.size + delta * direction);
     dragSizeRef.current = next;
-    panel.style[isHorizontal ? 'width' : 'height'] = `${next}px`;
+    if (onDrag) {
+      onDrag(next);
+    } else if (panelRef) {
+      const panel = panelRef.current;
+      if (panel) panel.style[isHorizontal ? 'width' : 'height'] = `${next}px`;
+    }
     e.currentTarget.setAttribute('aria-valuenow', String(Math.round(next)));
   };
 
@@ -174,6 +215,7 @@ export function PanelResizeHandle({
       onPointerCancel={endDrag}
       onLostPointerCapture={endDrag}
       onKeyDown={handleKeyDown}
+      onDoubleClick={onReset}
       className={cn(
         'group absolute z-20 flex touch-none select-none',
         'outline-none ring-0 focus:outline-none focus:ring-0 focus-visible:outline-none focus-visible:ring-0',

package/src/hooks/ui/index.ts

@@ -9,6 +9,7 @@ export * from './use-header-height';
 export * from './use-sticky-toolbar';
 export * from './use-horizontal-scrollbar';
 export * from './use-image-edge-color';
+export * from './use-clipped-label-tooltip';
 export * from './use-is-truncated';
 export * from './use-isomorphic-layout-effect';
 export * from './use-keyboard-collision-padding';

package/src/hooks/ui/use-clipped-label-tooltip.ts

@@ -0,0 +1,20 @@
+'use client';
+
+import { useIsTruncated } from './use-is-truncated';
+import { useMediaQuery } from './use-media-query';
+
+/** A pointer that can hover: where a tooltip on a clipped label is reachable. A touch screen has none. */
+export const HOVER_MEDIA_QUERY = '(hover: hover) and (pointer: fine)';
+
+/**
+ * A clipped label's "full text" tooltip: `ref` goes on the clipped element (see
+ * {@link useIsTruncated}), `enabled` says whether the tooltip may open — only
+ * while the text IS clipped, and only on a device whose pointer can hover. A
+ * phone or tablet has no hover to reach it with, so it offers none there; the
+ * rows keep their accessible names. Pass the rendered text as `value`.
+ */
+export function useClippedLabelTooltip<T extends HTMLElement>(value: unknown) {
+  const { ref, isTruncated } = useIsTruncated<T>(value);
+  const canHover = useMediaQuery(HOVER_MEDIA_QUERY) === true;
+  return { ref, enabled: isTruncated && canHover };
+}

package/src/hooks/ui/use-is-truncated.ts

@@ -52,6 +52,8 @@ export function useIsTruncated<T extends HTMLElement>(value: unknown, options?:
       );
     };
     check();
+    // An environment without ResizeObserver (jsdom in a consumer's tests) measures once.
+    if (typeof ResizeObserver === 'undefined') return undefined;
     const observer = new ResizeObserver(check);
     observer.observe(element);
     return () => observer.disconnect();

package/src/hooks/ui/use-media-query.ts

@@ -13,6 +13,8 @@ export function useMediaQuery(query: string): boolean | undefined {
   const [matches, setMatches] = useState<boolean | undefined>(undefined);
 
   useIsomorphicLayoutEffect(() => {
+    // An environment without matchMedia (jsdom in a consumer's tests) never answers: `undefined` throughout.
+    if (typeof window.matchMedia !== 'function') return undefined;
     const matchMedia = window.matchMedia(query);
 
     const handleChange = () => {

package/src/hooks/ui/use-resizable-panel-size.ts

@@ -110,5 +110,11 @@ export function useResizablePanelSize({
     [clampSize, storage],
   );
 
-  return { size, setSize, clampSize };
+  /** Back to `defaultSize`: the choice is forgotten and its stored entry removed. */
+  const resetSize = useCallback(() => {
+    setChosen({ storage, size: null });
+    storage?.clear();
+  }, [storage]);
+
+  return { size, setSize, resetSize, clampSize };
 }

package/src/types/navigation.ts

@@ -115,6 +115,35 @@ export interface SlidingSidebarConfig {
   className?: string;
 }
 
+/**
+ * `NavigationSidebarConfig.resizable`: the user drags the expanded sidebar's
+ * right edge on desktop (`lg` and up). The 56px rail is not resizable, nor are
+ * the tablet overlay and the burger menu; the overlay opens to the chosen width.
+ */
+export interface NavigationSidebarResizeConfig {
+  /**
+   * Narrowest expanded width, in px. Raised to 141px when lower: the rows read
+   * 140px and up as expanded (`@[140px]/of-nav-sidebar`).
+   */
+  minWidth: number;
+  /** Widest expanded width, in px. Also kept to the room there is (`minContentWidth`). */
+  maxWidth: number;
+  /**
+   * Px of the row the content beside the sidebar always keeps, so a wide sidebar
+   * cannot crowd the page out of a narrow desktop window. Default 720, the lib's
+   * `content-md` breakpoint.
+   */
+  minContentWidth?: number;
+  /**
+   * `localStorage` key for the width the user chose: `{ size }` under
+   * `<storageKey>:chosen` (see `useResizablePanelSize`). Only a drag or a key
+   * press on the handle writes it, never the default or a clamped width; a double
+   * click removes it. Omit to keep the choice for the mount only. A host that seeds
+   * `NAVIGATION_SIDEBAR_WIDTH_VAR` before first paint reads the same entry.
+   */
+  storageKey?: string;
+}
+
 /**
  * Configuration for the navigation sidebar component
  */
@@ -237,6 +266,14 @@ export interface NavigationSidebarConfig {
    * chat search in `sectionSlot`.
    */
   revealSignal?: number;
+  /**
+   * Let the user resize the expanded sidebar on desktop: a drag handle astride
+   * its right edge (the grip the Mingo chat drawer had), arrow keys, Home and
+   * End on it, a double click back to the default. The default stays
+   * `expandedWidth` (grouped) or 224px (flat); both variants. Omitted: the fixed
+   * widths, as before.
+   */
+  resizable?: NavigationSidebarResizeConfig;
 }
 
 /** What a slot render function is told about the place it is drawn in. */

package/src/utils/notifications.ts

@@ -39,6 +39,7 @@ export const NOTIFICATION_CATEGORIES = [
   'INSIGHTS',
   'MINGO',
   'INTEGRATIONS',
+  'BILLING',
   'GENERIC',
 ] as const;
 export type NotificationCategory = (typeof NOTIFICATION_CATEGORIES)[number];
@@ -56,6 +57,7 @@ export const NOTIFICATION_CATEGORY_LABELS: Readonly<Record<NotificationCategory,
   INSIGHTS: 'Insights',
   MINGO: 'Mingo',
   INTEGRATIONS: 'Integrations',
+  BILLING: 'Billing',
   GENERIC: 'General',
 };