noecosystem-design 0.1.0

package/packages/ui/src/theme-provider.tsx

@@ -0,0 +1,417 @@
+import * as React from 'react';
+
+import {
+  DEFAULT_PALETTE as TOKEN_DEFAULT_PALETTE,
+  PALETTE_COOKIE_KEY as TOKEN_PALETTE_COOKIE_KEY,
+  PALETTE_STORAGE_KEY as TOKEN_PALETTE_STORAGE_KEY,
+  PALETTES as TOKEN_PALETTES,
+  type Palette as TokenPalette,
+  isPalette as isTokenPalette,
+} from '@noe/design-tokens/palette';
+import { tokens } from '@noe/design-tokens';
+
+export type ThemePreference = 'light' | 'dark' | 'system';
+export type ResolvedTheme = 'light' | 'dark';
+export type NoeTheme = ThemePreference;
+
+export const PALETTES = TOKEN_PALETTES;
+export type Palette = TokenPalette;
+export const DEFAULT_PALETTE: Palette = TOKEN_DEFAULT_PALETTE;
+// Re-export token-backed check for external consumers
+export const isPalette = isTokenPalette;
+
+const STORAGE_KEY = 'noecosystem-theme';
+const EXPLORER_KEY = 'theme';
+const COOKIE_KEY = 'noecosystem-theme';
+const PALETTE_STORAGE_KEY = TOKEN_PALETTE_STORAGE_KEY;
+const PALETTE_COOKIE_KEY = TOKEN_PALETTE_COOKIE_KEY;
+
+type ThemeContextValue = {
+  theme: ThemePreference;
+  resolvedTheme: ResolvedTheme;
+  setTheme: (next: ThemePreference) => void;
+  toggle: () => void;
+  palette: Palette;
+  setPalette: (next: Palette) => void;
+};
+
+const ThemeContext = React.createContext<ThemeContextValue | null>(null);
+
+function isTheme(value: unknown): value is ResolvedTheme {
+  return value === 'light' || value === 'dark';
+}
+
+function readStorage(key: string): string | null {
+  try {
+    return window.localStorage.getItem(key);
+  } catch {
+    return null;
+  }
+}
+
+function writeStorage(key: string, value: string) {
+  try {
+    window.localStorage.setItem(key, value);
+  } catch {}
+}
+
+function removeStorage(key: string) {
+  try {
+    window.localStorage.removeItem(key);
+  } catch {}
+}
+
+function readCookie(cookieKey: string = COOKIE_KEY): string | null {
+  try {
+    const prefix = `${cookieKey}=`;
+    const entry = document.cookie
+      .split(';')
+      .map((part) => part.trim())
+      .find((part) => part.startsWith(prefix));
+    return entry ? decodeURIComponent(entry.slice(prefix.length)) : null;
+  } catch {
+    return null;
+  }
+}
+
+function writeCookie(theme: string, cookieKey: string = COOKIE_KEY) {
+  if (typeof window === 'undefined' || typeof document === 'undefined') return;
+  const sharedDomain =
+    window.location.hostname === 'noecosystem.com' ||
+    window.location.hostname.endsWith('.noecosystem.com')
+      ? '; Domain=.noecosystem.com'
+      : '';
+  const secure =
+    typeof window !== 'undefined' && window.location.protocol === 'https:' ? '; Secure' : '';
+  document.cookie = `${cookieKey}=${encodeURIComponent(theme)}; Path=/; Max-Age=31536000; SameSite=Lax${sharedDomain}${secure}`;
+}
+
+function preferredTheme(): ResolvedTheme {
+  if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return 'dark';
+  return window.matchMedia('(prefers-color-scheme: light)').matches ? 'light' : 'dark';
+}
+
+function readStoredPreference(storageKey: string): ThemePreference | null {
+  const shared = readStorage(storageKey);
+  if (isTheme(shared)) return shared;
+  const cookie = readCookie(COOKIE_KEY);
+  if (isTheme(cookie)) return cookie;
+  const explorer = readStorage(EXPLORER_KEY);
+  if (isTheme(explorer)) return explorer;
+  return null;
+}
+
+function resolveTheme(preference: ThemePreference): ResolvedTheme {
+  return preference === 'system' ? preferredTheme() : preference;
+}
+
+function readStoredPalette(storageKey: string): Palette | null {
+  const fromStorage = readStorage(storageKey);
+  if (isPalette(fromStorage)) return fromStorage as Palette;
+  const paletteCookie = readCookie(storageKey);
+  if (isPalette(paletteCookie)) return paletteCookie as Palette;
+  const fallbackCookie = storageKey !== PALETTE_COOKIE_KEY ? readCookie(PALETTE_COOKIE_KEY) : null;
+  if (isPalette(fallbackCookie)) return fallbackCookie as Palette;
+  return null;
+}
+
+function writePaletteStorage(palette: Palette, storageKey: string) {
+  writeStorage(storageKey, palette);
+  if (typeof document !== 'undefined') {
+    const sharedDomain =
+      window.location.hostname === 'noecosystem.com' ||
+      window.location.hostname.endsWith('.noecosystem.com')
+        ? '; Domain=.noecosystem.com'
+        : '';
+    const secure = window.location.protocol === 'https:' ? '; Secure' : '';
+    document.cookie = `${storageKey}=${encodeURIComponent(palette)}; Path=/; Max-Age=31536000; SameSite=Lax${sharedDomain}${secure}`;
+    if (storageKey !== PALETTE_COOKIE_KEY) {
+      document.cookie = `${PALETTE_COOKIE_KEY}=${encodeURIComponent(palette)}; Path=/; Max-Age=31536000; SameSite=Lax${sharedDomain}${secure}`;
+    }
+  }
+}
+
+function removePaletteStorage(storageKey: string) {
+  removeStorage(storageKey);
+  if (storageKey !== PALETTE_STORAGE_KEY) removeStorage(PALETTE_STORAGE_KEY);
+  try {
+    if (typeof document !== 'undefined') {
+      document.cookie = `${storageKey}=; Path=/; Max-Age=0; SameSite=Lax`;
+      if (storageKey !== PALETTE_COOKIE_KEY) {
+        document.cookie = `${PALETTE_COOKIE_KEY}=; Path=/; Max-Age=0; SameSite=Lax`;
+      }
+    }
+  } catch {}
+}
+
+function applyPaletteToDocument(palette: Palette) {
+  if (typeof document === 'undefined') return;
+  const root = document.documentElement;
+  root.setAttribute('data-noe-palette', palette);
+  (root as HTMLElement).dataset.noePalette = palette;
+}
+
+function applyThemeToDocument(theme: ResolvedTheme) {
+  if (typeof document === 'undefined') return;
+  const root = document.documentElement;
+  root.dataset.theme = theme;
+  root.classList.toggle('light', theme === 'light');
+  root.classList.toggle('dark', theme === 'dark');
+  root.style.colorScheme = theme;
+  const meta = document.querySelector<HTMLMetaElement>('meta[name="theme-color"]');
+  if (meta) {
+    const lightFallback = (tokens as unknown as { primitive: { color: { paper: Record<string, string> } } }).primitive?.color?.paper?.['100'] ?? '#f3f0ea';
+    const darkFallback = (tokens as unknown as { primitive: { color: { ink: Record<string, string> } } }).primitive?.color?.ink?.['950'] ?? '#252423';
+    const light = meta.getAttribute('data-theme-light') ?? lightFallback;
+    const dark = meta.getAttribute('data-theme-dark') ?? darkFallback;
+    meta.setAttribute('content', theme === 'light' ? light : dark);
+  }
+  if (typeof window !== 'undefined') {
+    window.dispatchEvent(new CustomEvent('noecosystem-themechange', { detail: { theme } }));
+  }
+}
+
+export function ThemeProvider({
+  children,
+  defaultTheme = 'system',
+  storageKey = STORAGE_KEY,
+  defaultPalette = DEFAULT_PALETTE,
+  paletteStorageKey = PALETTE_STORAGE_KEY,
+}: {
+  children: React.ReactNode;
+  defaultTheme?: ThemePreference;
+  storageKey?: string;
+  defaultPalette?: Palette;
+  paletteStorageKey?: string;
+}) {
+  const [preference, setPreference] = React.useState<ThemePreference>(() => {
+    if (typeof window === 'undefined') return defaultTheme;
+    if (defaultTheme !== 'system' && isTheme(defaultTheme)) return defaultTheme;
+    const stored = readStoredPreference(storageKey);
+    return stored ?? 'system';
+  });
+
+  const [resolvedTheme, setResolvedTheme] = React.useState<ResolvedTheme>(() => {
+    if (typeof window === 'undefined') return 'dark';
+    if (preference !== 'system' && isTheme(preference)) return preference;
+    const stored = readStoredPreference(storageKey);
+    if (stored && isTheme(stored)) return stored;
+    if (typeof window !== 'undefined' && defaultTheme !== 'system' && isTheme(defaultTheme))
+      return defaultTheme;
+    return preferredTheme();
+  });
+
+  const [palette, setPaletteState] = React.useState<Palette>(() => {
+    if (typeof window === 'undefined') return isPalette(defaultPalette) ? defaultPalette : DEFAULT_PALETTE;
+    const stored = readStoredPalette(paletteStorageKey);
+    if (stored && isPalette(stored)) return stored;
+    if (isPalette(defaultPalette)) return defaultPalette;
+    return DEFAULT_PALETTE;
+  });
+
+  const syncTheme = React.useCallback(
+    (nextPreference: ThemePreference) => {
+      const nextResolved = resolveTheme(nextPreference);
+      setPreference(nextPreference);
+      setResolvedTheme(nextResolved);
+      applyThemeToDocument(nextResolved);
+      if (nextPreference === 'system') {
+        removeStorage(storageKey);
+        removeStorage(EXPLORER_KEY);
+        try {
+          if (typeof document !== 'undefined') {
+            document.cookie = `${COOKIE_KEY}=; Path=/; Max-Age=0; SameSite=Lax`;
+          }
+        } catch {}
+      } else {
+        writeStorage(storageKey, nextPreference);
+        writeStorage(EXPLORER_KEY, nextPreference);
+        writeCookie(nextPreference, COOKIE_KEY);
+      }
+    },
+    [storageKey],
+  );
+
+  React.useEffect(() => {
+    if (defaultTheme !== 'system' && isTheme(defaultTheme)) {
+      syncTheme(defaultTheme);
+      return;
+    }
+    const stored = readStoredPreference(storageKey);
+    if (stored && isTheme(stored)) {
+      setPreference(stored);
+      setResolvedTheme(stored);
+      applyThemeToDocument(stored);
+    } else {
+      const sys = preferredTheme();
+      setPreference('system');
+      setResolvedTheme(sys);
+      applyThemeToDocument(sys);
+    }
+  }, [defaultTheme, syncTheme, storageKey]);
+
+  React.useEffect(() => {
+    if (preference !== 'system') return;
+    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return;
+    const media = window.matchMedia('(prefers-color-scheme: light)');
+    const onChange = () => {
+      const next = preferredTheme();
+      setResolvedTheme(next);
+      applyThemeToDocument(next);
+    };
+    media.addEventListener('change', onChange);
+    return () => media.removeEventListener('change', onChange);
+  }, [preference]);
+
+  React.useEffect(() => {
+    const onStorage = (event: StorageEvent) => {
+      if (event.key === storageKey) {
+        if (isTheme(event.newValue)) {
+          setPreference(event.newValue);
+          setResolvedTheme(event.newValue);
+          applyThemeToDocument(event.newValue);
+        } else if (event.newValue === null) {
+          const sys = preferredTheme();
+          setPreference('system');
+          setResolvedTheme(sys);
+          applyThemeToDocument(sys);
+        }
+      } else if (event.key === EXPLORER_KEY && !isTheme(readStorage(storageKey))) {
+        if (isTheme(event.newValue)) {
+          setPreference(event.newValue);
+          setResolvedTheme(event.newValue);
+          applyThemeToDocument(event.newValue);
+        } else if (event.newValue === null) {
+          const sys = preferredTheme();
+          setPreference('system');
+          setResolvedTheme(sys);
+          applyThemeToDocument(sys);
+        }
+      }
+    };
+    if (typeof window !== 'undefined') window.addEventListener('storage', onStorage);
+    return () => {
+      if (typeof window !== 'undefined') window.removeEventListener('storage', onStorage);
+    };
+  }, [storageKey]);
+
+  const syncPalette = React.useCallback(
+    (nextPalette: Palette) => {
+      const validated = isPalette(nextPalette) ? nextPalette : DEFAULT_PALETTE;
+      setPaletteState(validated);
+      applyPaletteToDocument(validated);
+      writePaletteStorage(validated, paletteStorageKey);
+    },
+    [paletteStorageKey],
+  );
+
+  React.useEffect(() => {
+    const stored = readStoredPalette(paletteStorageKey);
+    const initialPalette = stored && isPalette(stored) ? stored : isPalette(defaultPalette) ? defaultPalette : DEFAULT_PALETTE;
+    const validated = isPalette(initialPalette) ? initialPalette : DEFAULT_PALETTE;
+    setPaletteState(validated);
+    applyPaletteToDocument(validated);
+    if (!isPalette(stored)) {
+      writePaletteStorage(validated, paletteStorageKey);
+    }
+  }, [paletteStorageKey, defaultPalette]);
+
+  React.useEffect(() => {
+    const onStorage = (event: StorageEvent) => {
+      if (event.key === paletteStorageKey || event.key === PALETTE_STORAGE_KEY || event.key === PALETTE_COOKIE_KEY) {
+        if (isPalette(event.newValue)) {
+          setPaletteState(event.newValue as Palette);
+          applyPaletteToDocument(event.newValue as Palette);
+        } else if (event.newValue === null) {
+          const fallback = isPalette(defaultPalette) ? defaultPalette : DEFAULT_PALETTE;
+          setPaletteState(fallback);
+          applyPaletteToDocument(fallback);
+        } else {
+          setPaletteState(DEFAULT_PALETTE);
+          applyPaletteToDocument(DEFAULT_PALETTE);
+        }
+      }
+    };
+    if (typeof window !== 'undefined') window.addEventListener('storage', onStorage);
+    return () => {
+      if (typeof window !== 'undefined') window.removeEventListener('storage', onStorage);
+    };
+  }, [paletteStorageKey, defaultPalette]);
+
+  React.useEffect(() => {
+    return () => {
+      // Cleanup on unmount is not needed for persistence, but satisfy strict cleanup contract
+    };
+  }, []);
+
+  const setTheme = React.useCallback(
+    (next: ThemePreference) => {
+      syncTheme(next);
+    },
+    [syncTheme],
+  );
+
+  const toggle = React.useCallback(() => {
+    setTheme(resolvedTheme === 'dark' ? 'light' : 'dark');
+  }, [resolvedTheme, setTheme]);
+
+  const setPalette = React.useCallback(
+    (next: Palette) => {
+      syncPalette(next);
+    },
+    [syncPalette],
+  );
+
+  // Expose cleanup helper for tests that need to simulate logout/reset
+  const cleanupPalette = React.useCallback(() => {
+    removePaletteStorage(paletteStorageKey);
+  }, [paletteStorageKey]);
+
+  // Keep paletteStorageKey used to satisfy lint and support cleanup
+  void cleanupPalette;
+
+  const value = React.useMemo<ThemeContextValue>(
+    () => ({ theme: preference, resolvedTheme, setTheme, toggle, palette, setPalette }),
+    [preference, resolvedTheme, setTheme, toggle, palette, setPalette],
+  );
+
+  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
+}
+
+export function useTheme() {
+  const ctx = React.useContext(ThemeContext);
+  if (!ctx)
+    throw new Error(
+      'useTheme must be used within ThemeProvider — wrap your app with <ThemeProvider>.',
+    );
+  return ctx;
+}
+
+export function useThemeSafe(): ThemeContextValue | null {
+  return React.useContext(ThemeContext);
+}
+
+// Palette registry export for docs/tests
+export { PALETTE_STORAGE_KEY, PALETTE_COOKIE_KEY };
+
+// Theme init script — derives palettes from token registry to avoid duplication.
+// Uses graphitesque fallback if storage contains invalid value.
+const paletteListJson = JSON.stringify(TOKEN_PALETTES);
+export const themeInitScript = `(() => {try {
+  const STORAGE_KEY="noecosystem-theme",EXPLORER_KEY="theme",COOKIE_KEY="noecosystem-theme";
+  const PALETTE_KEY="${PALETTE_STORAGE_KEY}",PALETTE_COOKIE="${PALETTE_COOKIE_KEY}";
+  const PALETTES=${paletteListJson};
+  const isTheme=v=>v==="light"||v==="dark";
+  const isPalette=v=>PALETTES.includes(v);
+  const read=k=>{try{return localStorage.getItem(k)}catch{return null}};
+  const cookie=(k)=>{try{const p=k+"=";const e=document.cookie.split(";").map(s=>s.trim()).find(s=>s.startsWith(p));return e?decodeURIComponent(e.slice(p.length)):null}catch{return null}};
+  const sys=window.matchMedia("(prefers-color-scheme: light)").matches?"light":"dark";
+  let t=read(STORAGE_KEY); if(!isTheme(t)) t=cookie(COOKIE_KEY); if(!isTheme(t)) t=read(EXPLORER_KEY); if(!isTheme(t)) t=sys;
+  document.documentElement.dataset.theme=t;
+  document.documentElement.classList.toggle("light",t==="light");
+  document.documentElement.classList.toggle("dark",t==="dark");
+  document.documentElement.style.colorScheme=t;
+  let p=read(PALETTE_KEY); if(!isPalette(p)) p=cookie(PALETTE_COOKIE); if(!isPalette(p)) p=cookie("${PALETTE_COOKIE_KEY}"); if(!isPalette(p)) p="${DEFAULT_PALETTE}";
+  document.documentElement.setAttribute("data-noe-palette",p);
+  document.documentElement.dataset.noePalette=p;
+} catch {}})();`;

package/packages/ui/src/theme-toggle.tsx

@@ -0,0 +1,107 @@
+import { MoonIcon, SunIcon } from '@noe/icons';
+import type * as React from 'react';
+import { Button } from './button';
+import { cn } from './lib/cn';
+import { t } from './lib/i18n-messages';
+import { useThemeSafe } from './theme-provider';
+
+export interface ThemeToggleProps
+  extends Omit<
+    React.ComponentProps<typeof Button>,
+    'onClick' | 'type' | 'aria-label' | 'aria-pressed'
+  > {
+  /**
+   * Whether to show a text label next to the icon.
+   * When true, the button displays the current theme label.
+   */
+  showLabel?: boolean;
+  /** Accessible label override — defaults to i18n-aware "Toggle theme" */
+  'aria-label'?: string;
+  /** Locale for i18n messages — defaults to en. Pass fa for Persian. */
+  locale?: string;
+}
+
+/**
+ * ThemeToggle — composes the canonical Button primitive.
+ *
+ * - Uses `useTheme()` for single-source-of-truth theme switching.
+ * - No raw button element; delegates keyboard/focus to Button.
+ * - Prevents prop spreading from overriding internal onClick/type/accessible name.
+ * - Labels are intended to come from i18n messages: theme.toggle.light / theme.toggle.dark.
+ *   This component accepts an explicit aria-label but does not hardcode Persian/English inspection of document.lang.
+ * - Icons use the icons package (SunIcon/MoonIcon) rather than raw inline SVG.
+ * - showLabel is respected: when true, renders text; otherwise icon-only with sr-only label.
+ */
+export function ThemeToggle({
+  className,
+  showLabel = false,
+  variant = 'ghost',
+  size = 'icon',
+  'aria-label': ariaLabelProp,
+  locale,
+  ...rest
+}: ThemeToggleProps) {
+  const ctx = useThemeSafe();
+  // Single controller: ThemeProvider is the only writer to document/localStorage.
+  // Outside provider, we do not mutate storage — render fallback and no-op toggle (warn in dev).
+  const resolvedTheme: 'light' | 'dark' = ctx?.resolvedTheme ?? 'light';
+  const toggle =
+    ctx?.toggle ??
+    (() => {
+      if (process.env.NODE_ENV !== 'production') {
+        console.warn(
+          '[ThemeToggle] rendered outside ThemeProvider — toggle is no-op. Wrap with ThemeProvider.',
+        );
+      }
+    });
+  const isLight = resolvedTheme === 'light';
+
+  // i18n-aware labels — via message layer, not document.lang; locale prop drives language.
+  const defaultLabel = isLight ? t(locale, 'theme.toggle.dark') : t(locale, 'theme.toggle.light');
+  const accessibleLabel = ariaLabelProp ?? defaultLabel;
+  const title = accessibleLabel;
+  const showLabelText = isLight
+    ? t(locale, 'theme.preference.light')
+    : t(locale, 'theme.preference.dark');
+
+  const handleClick = (e: React.MouseEvent<HTMLButtonElement>) => {
+    e.preventDefault();
+    toggle();
+  };
+
+  return (
+    <Button
+      {...rest}
+      variant={variant}
+      size={showLabel ? 'sm' : size}
+      type={'button' as const}
+      aria-label={accessibleLabel}
+      title={title}
+      aria-pressed={isLight}
+      data-theme={resolvedTheme}
+      data-noecosystem-theme-toggle=""
+      className={cn('noe-theme-toggle', showLabel && 'gap-2 px-3', className)}
+      onClick={handleClick as never}
+    >
+      <span className="relative grid size-5 place-items-center" aria-hidden="true">
+        <SunIcon
+          className={cn(
+            'absolute size-5 transition-opacity',
+            isLight ? 'opacity-0' : 'opacity-100',
+          )}
+        />
+        <MoonIcon
+          className={cn(
+            'absolute size-5 transition-opacity',
+            isLight ? 'opacity-100' : 'opacity-0',
+          )}
+        />
+      </span>
+      {showLabel ? (
+        <span className="text-sm">{showLabelText}</span>
+      ) : (
+        <span className="sr-only">{accessibleLabel}</span>
+      )}
+    </Button>
+  );
+}

package/packages/ui/src/toggle.tsx

@@ -0,0 +1,34 @@
+import type * as React from 'react';
+import { cn } from './lib/cn';
+export interface ToggleProps extends React.ComponentProps<'button'> {
+  pressed?: boolean;
+}
+export function Toggle({
+  className,
+  pressed,
+  children,
+  ...props
+}: ToggleProps & { 'aria-label'?: string }) {
+  const ariaLabel = (props as { 'aria-label'?: string })['aria-label'] ?? 'Toggle';
+  return (
+    <button
+      role="switch"
+      aria-checked={!!pressed}
+      aria-label={ariaLabel}
+      data-state={pressed ? 'on' : 'off'}
+      className={cn(
+        'inline-flex h-6 w-10 items-center rounded-pill border border-border bg-muted p-0.5 transition-colors data-[state=on]:bg-accent',
+        className,
+      )}
+      data-slot="toggle"
+      {...props}
+    >
+      <span
+        className={cn(
+          'size-5 rounded-pill bg-surface-raised shadow transition-transform',
+          pressed ? 'translate-x-4' : 'translate-x-0',
+        )}
+      />
+    </button>
+  );
+}

package/packages/ui/src/tooltip.tsx

@@ -0,0 +1,50 @@
+import { Tooltip as TooltipPrimitive } from '@base-ui/react/tooltip';
+import type * as React from 'react';
+
+import { useDirection } from './direction';
+import { cn } from './lib/cn';
+
+export const Tooltip = TooltipPrimitive.Root;
+export const TooltipProvider = TooltipPrimitive.Provider;
+
+export function TooltipTrigger({
+  className,
+  ...props
+}: React.ComponentProps<typeof TooltipPrimitive.Trigger>) {
+  return (
+    <TooltipPrimitive.Trigger className={cn(className)} data-slot="tooltip-trigger" {...props} />
+  );
+}
+
+export interface TooltipPopupProps extends React.ComponentProps<typeof TooltipPrimitive.Popup> {
+  portalProps?: React.ComponentProps<typeof TooltipPrimitive.Portal>;
+  positionerProps?: React.ComponentProps<typeof TooltipPrimitive.Positioner>;
+}
+
+export function TooltipPopup({
+  className,
+  children,
+  portalProps,
+  positionerProps,
+  ...props
+}: TooltipPopupProps) {
+  const direction = useDirection();
+
+  return (
+    <TooltipPrimitive.Portal {...portalProps}>
+      <TooltipPrimitive.Positioner sideOffset={6} {...positionerProps}>
+        <TooltipPrimitive.Popup
+          className={cn(
+            'z-(--noe-z-index-overlay) max-w-64 rounded-md border border-border bg-foreground px-2.5 py-1.5 text-xs leading-normal text-background shadow-raised outline-none transition-[opacity,transform] duration-(--noe-motion-duration-fast) ease-standard data-[ending-style]:scale-95 data-[ending-style]:opacity-0 data-[starting-style]:scale-95 data-[starting-style]:opacity-0',
+            className,
+          )}
+          data-slot="tooltip-popup"
+          dir={direction}
+          {...props}
+        >
+          {children}
+        </TooltipPrimitive.Popup>
+      </TooltipPrimitive.Positioner>
+    </TooltipPrimitive.Portal>
+  );
+}

package/packages/ui/src/tree-view.tsx

@@ -0,0 +1,19 @@
+import type * as React from 'react';
+import { cn } from './lib/cn';
+export interface TreeViewProps extends React.ComponentProps<'div'> {
+  children?: React.ReactNode;
+}
+export function TreeView({ className, children, ...props }: TreeViewProps) {
+  return (
+    <div
+      className={cn(
+        'rounded-md border border-border bg-surface-raised p-4 text-sm text-foreground',
+        className,
+      )}
+      data-slot="tree-view"
+      {...props}
+    >
+      {children ?? 'Tree View'}
+    </div>
+  );
+}

package/packages/ui/src/utility-button.tsx

@@ -0,0 +1,33 @@
+import { Button, type ButtonProps } from './button';
+import { cn } from './lib/cn';
+
+export interface UtilityButtonProps extends Omit<ButtonProps, 'variant' | 'size'> {
+  /** Visual intent — maps to Button variants but constrained to utility-appropriate set */
+  variant?: 'quiet' | 'ghost' | 'outline' | 'secondary';
+  size?: 'sm' | 'md' | 'lg' | 'icon';
+  /** Accessible label required for icon-only usage */
+  'aria-label': string;
+}
+
+/**
+ * UtilityButton — narrow-crown toolbar/icon action.
+ * Composes canonical Button primitive (no second primitive).
+ * Use for: toolbar actions, row-level utilities, compact icon triggers.
+ * Do not use for: primary form submission, destructive confirmation (use Button variant destructive).
+ */
+export function UtilityButton({
+  className,
+  variant = 'ghost',
+  size = 'icon',
+  ...props
+}: UtilityButtonProps) {
+  return (
+    <Button
+      variant={variant}
+      size={size}
+      className={cn('shrink-0', className)}
+      data-slot="utility-button"
+      {...props}
+    />
+  );
+}

package/packages/ui/src/utils.ts

@@ -0,0 +1,13 @@
+export { cn, cn as cx } from './lib/cn';
+
+export type LogicalSide = 'start' | 'end' | 'top' | 'bottom';
+
+/** Converts a logical placement to the physical swipe direction required by Base UI. */
+export function resolveLogicalSide(
+  side: LogicalSide,
+  direction: 'ltr' | 'rtl',
+): 'left' | 'right' | 'top' | 'bottom' {
+  if (side === 'top' || side === 'bottom') return side;
+  if (side === 'start') return direction === 'rtl' ? 'right' : 'left';
+  return direction === 'rtl' ? 'left' : 'right';
+}