@xenide-io/the-old-ui-theme 0.3.2 → 0.4.3

package/src/suite/icons/glyphs.ts

@@ -0,0 +1,203 @@
+/**
+ * Suite icon glyph definitions — pure path data, no React.
+ *
+ * Shared geometric grammar (lucide-compatible):
+ * - 24×24 viewBox
+ * - 2px strokes, round caps/joins (set by the renderer)
+ * - `fill="none" stroke="currentColor"` unless `filled: true`
+ *
+ * Elements flagged `accent: true` are rendered inside a group coloured by
+ * `var(--suite-icon-accent, currentColor)` — `<SuiteIcon accent="…">` sets the
+ * variable from `app-accents.ts`; without an accent they inherit the text
+ * colour like any lucide icon.
+ */
+
+export type SuiteGlyphElement =
+  | {
+      kind: 'path';
+      d: string;
+      accent?: boolean;
+      filled?: boolean;
+    }
+  | {
+      kind: 'circle';
+      cx: number;
+      cy: number;
+      r: number;
+      accent?: boolean;
+      filled?: boolean;
+    }
+  | {
+      kind: 'rect';
+      x: number;
+      y: number;
+      width: number;
+      height: number;
+      rx?: number;
+      accent?: boolean;
+      filled?: boolean;
+    };
+
+export interface SuiteGlyph {
+  /** One-line description of what the mark depicts (used in docs/sheets). */
+  description: string;
+  elements: SuiteGlyphElement[];
+  /**
+   * The accent group carries a subtle CSS animation (today-sun rays only).
+   * Renderers must honour prefers-reduced-motion; see suite-icon.tsx.
+   */
+  animatedAccent?: boolean;
+}
+
+export type SuiteIconName =
+  | 'timer-shell'
+  | 'kanban-wave'
+  | 'squid-doc'
+  | 'stack-hex'
+  | 'crew-bot'
+  | 'workspace'
+  | 'organisation'
+  | 'integration-plug'
+  | 'suite-grid'
+  | 'bell-wave'
+  | 'today-sun';
+
+export const SUITE_GLYPHS: Record<SuiteIconName, SuiteGlyph> = {
+  'timer-shell': {
+    description: 'TurtleTime — turtle-shell dome holding clock hands',
+    elements: [
+      { kind: 'path', d: 'M3 17h18' },
+      { kind: 'path', d: 'M6.5 17a5.5 5.5 0 0 1 11 0' },
+      { kind: 'circle', cx: 4, cy: 15.3, r: 1.5 },
+      { kind: 'path', d: 'M12 17v-3.4', accent: true },
+      { kind: 'path', d: 'M12 17l2.4-1.4', accent: true },
+    ],
+  },
+  'kanban-wave': {
+    description: 'Tides — three kanban bars riding a wave',
+    elements: [
+      { kind: 'rect', x: 5.5, y: 8, width: 3, height: 8, rx: 1.5 },
+      { kind: 'rect', x: 10.5, y: 5.5, width: 3, height: 10.5, rx: 1.5 },
+      { kind: 'rect', x: 15.5, y: 9.5, width: 3, height: 6.5, rx: 1.5 },
+      {
+        kind: 'path',
+        d: 'M3 19.5q2.25-2.4 4.5 0t4.5 0t4.5 0t4.5 0',
+        accent: true,
+      },
+    ],
+  },
+  'squid-doc': {
+    description: 'Kraken — squid with a pen-nib centre tentacle',
+    elements: [
+      {
+        kind: 'path',
+        d: 'M12 3.2c2.7 2.3 4.2 5.3 4.2 9.3H7.8c0-4 1.5-7 4.2-9.3Z',
+      },
+      { kind: 'circle', cx: 10.1, cy: 9, r: 0.9, filled: true },
+      { kind: 'circle', cx: 13.9, cy: 9, r: 0.9, filled: true },
+      { kind: 'path', d: 'M9.4 12.4v4.8q0 2.3-2.3 2.3' },
+      { kind: 'path', d: 'M14.6 12.4v4.8q0 2.3 2.3 2.3' },
+      { kind: 'path', d: 'M12 12.4v7.1', accent: true },
+    ],
+  },
+  'stack-hex': {
+    description: 'ShellStack — hexagon with the resolving spiral',
+    elements: [
+      { kind: 'path', d: 'M18 12l-3 5.2H9l-3-5.2 3-5.2h6Z' },
+      { kind: 'path', d: 'M14.2 9.3H9.8v5.4h4.4v-2.7h-2.2', accent: true },
+    ],
+  },
+  'crew-bot': {
+    description: 'Crew — friendly robot head with antenna and smile',
+    elements: [
+      { kind: 'path', d: 'M12 7.5V5' },
+      { kind: 'circle', cx: 12, cy: 4, r: 1, filled: true },
+      { kind: 'rect', x: 5, y: 8, width: 14, height: 9.5, rx: 3 },
+      { kind: 'path', d: 'M5 11.8H3.4' },
+      { kind: 'path', d: 'M19 11.8h1.6' },
+      { kind: 'circle', cx: 9.2, cy: 11.8, r: 1, filled: true },
+      { kind: 'circle', cx: 14.8, cy: 11.8, r: 1, filled: true },
+      { kind: 'path', d: 'M9.6 14.6q2.4 1.7 4.8 0', accent: true },
+    ],
+  },
+  workspace: {
+    description: 'Workspace container — panel with header bar and content',
+    elements: [
+      { kind: 'rect', x: 3.5, y: 4.5, width: 17, height: 15, rx: 2.5 },
+      { kind: 'path', d: 'M3.5 8.7h17' },
+      { kind: 'circle', cx: 6.2, cy: 6.6, r: 0.9, accent: true, filled: true },
+      { kind: 'path', d: 'M6.4 12.2h7' },
+      { kind: 'path', d: 'M6.4 15.4h10.5' },
+    ],
+  },
+  organisation: {
+    description: 'Organisation chart — root node with two members',
+    elements: [
+      { kind: 'rect', x: 9.5, y: 3.5, width: 5, height: 5, rx: 1.4, accent: true },
+      { kind: 'path', d: 'M12 8.5v2.5' },
+      { kind: 'path', d: 'M6.75 13.5v-2.5h10.5v2.5' },
+      { kind: 'rect', x: 4.25, y: 13.5, width: 5, height: 5, rx: 1.4 },
+      { kind: 'rect', x: 14.75, y: 13.5, width: 5, height: 5, rx: 1.4 },
+    ],
+  },
+  'integration-plug': {
+    description: 'Integration — two plug halves meeting under a spark',
+    elements: [
+      { kind: 'rect', x: 3.2, y: 9.8, width: 5.6, height: 4.6, rx: 1.4 },
+      { kind: 'path', d: 'M8.8 11h2.4' },
+      { kind: 'path', d: 'M8.8 13.2h2.4' },
+      { kind: 'rect', x: 15.2, y: 9.8, width: 5.6, height: 4.6, rx: 1.4 },
+      { kind: 'path', d: 'M15.2 11h-2.4' },
+      { kind: 'path', d: 'M15.2 13.2h-2.4' },
+      { kind: 'path', d: 'M6 14.4v2q0 1.4-1.4 1.4H3.4' },
+      { kind: 'path', d: 'M18 14.4v2q0 1.4 1.4 1.4h1.2' },
+      { kind: 'path', d: 'M12 4.4v2.4', accent: true },
+      { kind: 'path', d: 'M10.4 5l3.2 1.2', accent: true },
+      { kind: 'path', d: 'M13.6 5l-3.2 1.2', accent: true },
+    ],
+  },
+  'suite-grid': {
+    description: 'Suite app switcher — four tiles, the active app filled',
+    elements: [
+      { kind: 'rect', x: 4, y: 4, width: 7, height: 7, rx: 2 },
+      { kind: 'rect', x: 13, y: 4, width: 7, height: 7, rx: 2 },
+      { kind: 'rect', x: 4, y: 13, width: 7, height: 7, rx: 2 },
+      {
+        kind: 'rect',
+        x: 13,
+        y: 13,
+        width: 7,
+        height: 7,
+        rx: 2,
+        accent: true,
+        filled: true,
+      },
+    ],
+  },
+  'bell-wave': {
+    description: 'Notifications — bell with sound waves',
+    elements: [
+      { kind: 'path', d: 'M7 9.2a5 5 0 0 1 10 0c0 5.3 2.4 7.3 2.4 7.3H4.6S7 14.5 7 9.2' },
+      { kind: 'path', d: 'M10.7 19.3a1.5 1.5 0 0 0 2.6 0' },
+      { kind: 'path', d: 'M17.9 6.4a5.5 5.5 0 0 1 1.4 3.7', accent: true },
+      { kind: 'path', d: 'M15.7 4a9.4 9.4 0 0 1 2.4 6', accent: true },
+    ],
+  },
+  'today-sun': {
+    description: 'Today — sun with slowly turning rays (motion-safe)',
+    animatedAccent: true,
+    elements: [
+      { kind: 'circle', cx: 12, cy: 12, r: 4 },
+      { kind: 'path', d: 'M12 2.8v2.4', accent: true },
+      { kind: 'path', d: 'M12 18.8v2.4', accent: true },
+      { kind: 'path', d: 'M2.8 12h2.4', accent: true },
+      { kind: 'path', d: 'M18.8 12h2.4', accent: true },
+      { kind: 'path', d: 'M5.5 5.5l1.7 1.7', accent: true },
+      { kind: 'path', d: 'M16.8 16.8l1.7 1.7', accent: true },
+      { kind: 'path', d: 'M5.5 18.5l1.7-1.7', accent: true },
+      { kind: 'path', d: 'M16.8 7.2l1.7-1.7', accent: true },
+    ],
+  },
+};
+
+export const SUITE_ICON_NAMES = Object.keys(SUITE_GLYPHS) as SuiteIconName[];

package/src/suite/icons/index.ts

@@ -0,0 +1,12 @@
+export { APP_ACCENTS, APP_GLYPHS } from './app-accents';
+export type { SuiteAccentSlug, SuiteAppAccent } from './app-accents';
+export { SUITE_GLYPHS, SUITE_ICON_NAMES } from './glyphs';
+export type {
+  SuiteGlyph,
+  SuiteGlyphElement,
+  SuiteIconName,
+} from './glyphs';
+export { SuiteIcon } from './suite-icon';
+export type { SuiteIconProps } from './suite-icon';
+export { SuiteAppIcon } from './suite-app-icon';
+export type { SuiteAppIconProps } from './suite-app-icon';

package/src/suite/icons/suite-app-icon.tsx

@@ -0,0 +1,68 @@
+'use client';
+
+import type { CSSProperties } from 'react';
+
+import { cn } from '../lib/cn';
+import { APP_ACCENTS, APP_GLYPHS, type SuiteAccentSlug } from './app-accents';
+import { GlyphParts } from './glyph-parts';
+import { SUITE_GLYPHS } from './glyphs';
+
+const SIZE_PRESETS = { sm: 28, md: 36, lg: 44 } as const;
+
+export interface SuiteAppIconProps {
+  app: SuiteAccentSlug;
+  /** px size, or a preset (sm 28 / md 36 / lg 44). */
+  size?: number | keyof typeof SIZE_PRESETS;
+  /** Accessible label; defaults to decorative (`aria-hidden`). */
+  label?: string;
+  className?: string;
+  style?: CSSProperties;
+}
+
+/**
+ * An app's simplified mark — brand tile + its suite glyph, drawn
+ * programmatically at any size (no cross-app <img> favicon lookups).
+ * Colours come from app-accents.ts.
+ */
+export function SuiteAppIcon({
+  app,
+  size = 'md',
+  label,
+  className,
+  style,
+}: SuiteAppIconProps) {
+  const px = typeof size === 'number' ? size : SIZE_PRESETS[size];
+  const brand = APP_ACCENTS[app];
+  const glyph = SUITE_GLYPHS[APP_GLYPHS[app]];
+
+  return (
+    <svg
+      width={px}
+      height={px}
+      viewBox="0 0 24 24"
+      className={cn('shrink-0', className)}
+      style={style}
+      role={label ? 'img' : undefined}
+      aria-label={label}
+      aria-hidden={label ? undefined : true}
+    >
+      <rect x="1" y="1" width="22" height="22" rx="5.5" fill={brand.tile} />
+      <g
+        transform="translate(4.4 4.4) scale(0.6333)"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth={2.7}
+        strokeLinecap="round"
+        strokeLinejoin="round"
+        style={
+          {
+            color: brand.onTile,
+            '--suite-icon-accent': brand.onTileAccent,
+          } as CSSProperties
+        }
+      >
+        <GlyphParts elements={glyph.elements} />
+      </g>
+    </svg>
+  );
+}

package/src/suite/icons/suite-icon.tsx

@@ -0,0 +1,93 @@
+'use client';
+
+import type { CSSProperties } from 'react';
+
+import { cn } from '../lib/cn';
+import { APP_ACCENTS, type SuiteAccentSlug } from './app-accents';
+import { GlyphParts } from './glyph-parts';
+import { SUITE_GLYPHS, type SuiteIconName } from './glyphs';
+
+/**
+ * Motion for the only animated glyph (today-sun): rays turn slowly, and only
+ * when the user has not asked for reduced motion. Mirrors the injected-style
+ * pattern used by the app logo components.
+ */
+const TODAY_SUN_STYLE = `
+@media (prefers-reduced-motion: no-preference) {
+  .suite-icon-today-sun-rays {
+    animation: suite-icon-today-sun-spin 18s linear infinite;
+    transform-box: fill-box;
+    transform-origin: center;
+  }
+}
+@keyframes suite-icon-today-sun-spin {
+  to { transform: rotate(360deg); }
+}
+`;
+
+export interface SuiteIconProps {
+  name: SuiteIconName;
+  /** px size; a Tailwind sizing class on `className` also works. */
+  size?: number | string;
+  /** App slug — tints the glyph's accent layer with the app's brand hex. */
+  accent?: SuiteAccentSlug;
+  strokeWidth?: number;
+  /** Only today-sun animates; set false to freeze it. Reduced-motion safe. */
+  animated?: boolean;
+  /** Accessible label. Without it the icon is `aria-hidden` (decorative). */
+  label?: string;
+  className?: string;
+  style?: CSSProperties;
+}
+
+/**
+ * Suite icon — hand-drawn glyphs on the lucide grammar (24×24, 2px strokes,
+ * round caps/joins). Strokes inherit `currentColor`, so ph-* text tokens just
+ * work; `accent` adds a per-app brand tint to the glyph's accent layer.
+ */
+export function SuiteIcon({
+  name,
+  size = 24,
+  accent,
+  strokeWidth = 2,
+  animated = true,
+  label,
+  className,
+  style,
+}: SuiteIconProps) {
+  const glyph = SUITE_GLYPHS[name];
+  const accentHex = accent ? APP_ACCENTS[accent].accent : undefined;
+  const mergedStyle = accentHex
+    ? ({ ...style, '--suite-icon-accent': accentHex } as CSSProperties)
+    : style;
+
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={strokeWidth}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      className={cn('shrink-0', className)}
+      style={mergedStyle}
+      role={label ? 'img' : undefined}
+      aria-label={label}
+      aria-hidden={label ? undefined : true}
+    >
+      {glyph.animatedAccent && animated ? (
+        <style>{TODAY_SUN_STYLE}</style>
+      ) : null}
+      <GlyphParts
+        elements={glyph.elements}
+        accentClassName={
+          glyph.animatedAccent && animated
+            ? 'suite-icon-today-sun-rays'
+            : undefined
+        }
+      />
+    </svg>
+  );
+}

package/src/suite/index.ts

@@ -0,0 +1,108 @@
+export { TodayPageFrame } from './components/today-page-frame';
+export * from './components/today-ui';
+export {
+  AppSwitcher,
+  AppSwitcherChevron,
+  AppSwitcherMark,
+  appSwitcherMarkClass,
+  appSwitcherMenuItemClass,
+  appSwitcherTriggerClass,
+  type SuiteAppEntry,
+} from './components/app-switcher';
+export {
+  SuiteNotificationBell,
+  type SuiteNotification,
+  type SuiteNotificationsResponse,
+} from './components/suite-notification-bell';
+export { CommandPaletteHost } from './components/command-palette-host';
+export { DeferredChrome } from './components/deferred-chrome';
+export { SuiteMobileDrawer } from './components/suite-mobile-drawer';
+export { SuiteMobileHeader } from './components/suite-mobile-header';
+export {
+  SuiteUserMenu,
+  type SuiteUserMenuProps,
+} from './components/suite-user-menu';
+export {
+  SuiteBottomNav,
+  type SuiteBottomNavItem,
+} from './components/suite-bottom-nav';
+export {
+  SUITE_APPS,
+  SUITE_APP_MAP,
+  suiteAppBaseUrl,
+  type SuiteAppDefinition,
+  type SuiteAppSlug,
+} from './lib/apps';
+export { TodayCalibrating } from './components/today-calibrating';
+export {
+  SuiteThemeProvider,
+  useSuiteTheme,
+  type SuiteResolvedTheme,
+  type SuiteTheme,
+  type SuiteThemeConfig,
+  type SuiteThemeContextValue,
+} from './components/theme-provider';
+export {
+  SuiteAiPanel,
+  type SuiteAiPreset,
+} from './components/ai-panel';
+export {
+  APP_ACCENTS,
+  APP_GLYPHS,
+  SUITE_GLYPHS,
+  SUITE_ICON_NAMES,
+  SuiteAppIcon,
+  SuiteIcon,
+  type SuiteAccentSlug,
+  type SuiteAppAccent,
+  type SuiteAppIconProps,
+  type SuiteGlyph,
+  type SuiteGlyphElement,
+  type SuiteIconName,
+  type SuiteIconProps,
+} from './icons';
+export type {
+  SuiteCommandItem,
+  SuiteCommandPaletteComponent,
+  SuiteDropdownItemComponent,
+  SuiteDropdownMenuComponent,
+  SuiteDropdownMenuProps,
+  SuiteSpinnerComponent,
+} from './lib/injected';
+export { useIdleMount } from './lib/use-idle-mount';
+export { cn } from './lib/cn';
+export {
+  SuiteMotionProvider,
+  m,
+  SUITE_SPRINGS,
+  type SuiteSpringName,
+} from './lib/motion';
+export {
+  SuitePage,
+  SuitePageHeader,
+  SuiteBreadcrumbs,
+  SuiteToolbar,
+  SuiteTabList,
+  SuiteSectionHeader,
+  type SuitePageWidth,
+  type SuiteBreadcrumbsProps,
+} from './components/suite-layout';
+export {
+  SuiteSkeleton,
+  SuiteSkeletonCard,
+  SuiteSkeletonList,
+  SuiteEmptyState,
+} from './components/suite-skeleton';
+export {
+  SuiteSettingsMobileNav,
+  type SuiteSettingsNavItem,
+} from './components/suite-settings-mobile-nav';
+export {
+  SuiteSidebar,
+  type SuiteSidebarNavItem,
+} from './components/suite-sidebar';
+export {
+  SuiteAppLayout,
+  type SuiteAppLayoutProps,
+} from './components/suite-app-layout';
+

package/src/suite/lib/apps.ts

@@ -0,0 +1,75 @@
+/**
+ * The single source of truth for the ShellStack app family — used by the
+ * app switcher, mobile bottom nav, launchpad, and cross-app navigation.
+ * Slugs double as accent keys (see icons/app-accents.ts) and data-test
+ * suffixes (`switch-app-${slug}`, `suite-nav-${slug}`).
+ */
+
+export type SuiteAppSlug = 'shellstack' | 'tides' | 'turtletime' | 'kraken';
+
+export interface SuiteAppDefinition {
+  slug: SuiteAppSlug;
+  name: string;
+  description: string;
+  /** Public asset path — every app hosts all four icons. */
+  icon: string;
+  /** Landing route used after cross-app SSO redirect. */
+  landing: string;
+  /** Env var carrying the app's base URL (dev fallback included). */
+  baseUrlEnv: string;
+  baseUrlFallback: string;
+}
+
+/** Display order — launchpad first, then by daily workflow. */
+export const SUITE_APPS: readonly SuiteAppDefinition[] = [
+  {
+    slug: 'shellstack',
+    name: 'ShellStack',
+    description: 'Organisation and billing',
+    icon: '/icon-shellstack.svg',
+    landing: '/home',
+    baseUrlEnv: 'NEXT_PUBLIC_SHELLSTACK_URL',
+    baseUrlFallback: 'http://localhost:3002',
+  },
+  {
+    slug: 'tides',
+    name: 'Tides',
+    description: 'Projects and tasks',
+    icon: '/tides-icon.svg',
+    landing: '/today',
+    baseUrlEnv: 'NEXT_PUBLIC_TIDES_URL',
+    baseUrlFallback: 'http://localhost:3001',
+  },
+  {
+    slug: 'turtletime',
+    name: 'TurtleTime',
+    description: 'Time tracking',
+    icon: '/turtletime-icon.svg',
+    landing: '/tracker',
+    baseUrlEnv: 'NEXT_PUBLIC_TURTLETIME_URL',
+    baseUrlFallback: 'http://localhost:3000',
+  },
+  {
+    slug: 'kraken',
+    name: 'Kraken',
+    description: 'Documents and knowledge',
+    icon: '/kraken-icon.svg',
+    landing: '/today',
+    baseUrlEnv: 'NEXT_PUBLIC_KRAKEN_URL',
+    baseUrlFallback: 'http://localhost:3003',
+  },
+] as const;
+
+export const SUITE_APP_MAP: Readonly<Record<SuiteAppSlug, SuiteAppDefinition>> =
+  Object.fromEntries(SUITE_APPS.map((app) => [app.slug, app])) as Record<
+    SuiteAppSlug,
+    SuiteAppDefinition
+  >;
+
+/** Resolve an app's base URL: env var first, dev fallback second. */
+export function suiteAppBaseUrl(slug: SuiteAppSlug): string {
+  const def = SUITE_APP_MAP[slug];
+  const fromEnv =
+    typeof process !== 'undefined' ? process.env[def.baseUrlEnv] : undefined;
+  return (fromEnv || def.baseUrlFallback).replace(/\/$/, '');
+}

package/src/suite/lib/cn.ts

@@ -0,0 +1,6 @@
+import { clsx, type ClassValue } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}

package/src/suite/lib/injected.ts

@@ -0,0 +1,54 @@
+import type {
+  ButtonHTMLAttributes,
+  ComponentType,
+  ReactNode,
+} from 'react';
+
+/**
+ * Structural types for theme primitives each app injects from
+ * `@xenide-io/the-old-ui-theme/ui` (the shared package must not depend on it).
+ * The real components satisfy these shapes, so apps can pass them directly.
+ */
+
+export interface SuiteDropdownMenuProps {
+  trigger: ReactNode;
+  children: ReactNode;
+  'aria-label': string;
+  align?: 'start' | 'center' | 'end';
+  side?: 'top' | 'right' | 'bottom' | 'left';
+  sideOffset?: number;
+  className?: string;
+  panelClassName?: string;
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+}
+
+export type SuiteDropdownMenuComponent =
+  ComponentType<SuiteDropdownMenuProps>;
+
+export type SuiteDropdownItemComponent = ComponentType<
+  ButtonHTMLAttributes<HTMLButtonElement>
+>;
+
+export interface SuiteCommandItem {
+  id: string;
+  label: string;
+  shortcut?: string;
+  icon?: ReactNode;
+  onSelect: () => void;
+}
+
+export type SuiteCommandPaletteComponent = ComponentType<{
+  items: SuiteCommandItem[];
+  isOpen: boolean;
+  onClose: () => void;
+  placeholder?: string;
+  className?: string;
+}>;
+
+/** App-branded spinner (each app has its own AppSpinner design). */
+export type SuiteSpinnerComponent = ComponentType<{
+  size?: 'sm' | 'md' | 'lg';
+  className?: string;
+  label?: string;
+}>;

package/src/suite/lib/motion.tsx

@@ -0,0 +1,48 @@
+'use client';
+
+import { LazyMotion, domAnimation, m } from 'motion/react';
+import type { ReactNode } from 'react';
+
+/**
+ * Suite motion foundation.
+ *
+ * `LazyMotion` + `domAnimation` keeps the animation runtime (~15 kB) out of
+ * the initial bundle — features load with the first animated component.
+ * `strict` guarantees only the tree-shakeable `m` component is used inside
+ * the provider (never the heavier `motion` component).
+ *
+ * Usage:
+ *   <SuiteMotionProvider>
+ *     <m.div initial={{ opacity: 0 }} animate={{ opacity: 1 }} />
+ *   </SuiteMotionProvider>
+ *
+ * Prefer CSS transitions for micro-interactions (hover/press/colour) and
+ * reach for `m` only when you need springs, gestures, or layout animation.
+ */
+export function SuiteMotionProvider({ children }: { children: ReactNode }) {
+  return (
+    <LazyMotion features={domAnimation} strict>
+      {children}
+    </LazyMotion>
+  );
+}
+
+export { m };
+
+/**
+ * Spring presets — the JS counterparts of the `ease-spring-*` timing
+ * functions defined in each app's tailwind config. Use these for entrances,
+ * sheets, drawers, and press feedback so JS and CSS motion feel identical.
+ * All respect `prefers-reduced-motion` when paired with
+ * `MotionConfig reducedMotion="user"` or CSS `motion-reduce:` variants.
+ */
+export const SUITE_SPRINGS = {
+  /** Snappy panel/sheet entrances — small overshoot. */
+  fast: { type: 'spring', stiffness: 400, damping: 32, mass: 0.8 },
+  /** Gentle scrims, fades, list staggers. */
+  subtle: { type: 'spring', stiffness: 260, damping: 26, mass: 1 },
+  /** Press/tap feedback — quick settle, no wobble. */
+  press: { type: 'spring', stiffness: 600, damping: 35, mass: 0.5 },
+} as const;
+
+export type SuiteSpringName = keyof typeof SUITE_SPRINGS;

package/src/suite/lib/use-idle-mount.ts

@@ -0,0 +1,25 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+
+/** Mount non-critical chrome after the browser is idle (or a short timeout). */
+export function useIdleMount(timeoutMs = 1200): boolean {
+  const [ready, setReady] = useState(false);
+
+  useEffect(() => {
+    let timeoutId = 0;
+    let idleId = 0;
+
+    const activate = () => setReady(true);
+
+    if (typeof window.requestIdleCallback === 'function') {
+      idleId = window.requestIdleCallback(activate, { timeout: timeoutMs });
+      return () => window.cancelIdleCallback(idleId);
+    }
+
+    timeoutId = window.setTimeout(activate, Math.min(timeoutMs, 200));
+    return () => window.clearTimeout(timeoutId);
+  }, [timeoutMs]);
+
+  return ready;
+}