@drakkar.software/octospaces-ui 0.3.0 → 0.4.0

package/src/sidebar/Sidebar.tsx

@@ -0,0 +1,101 @@
+/**
+ * Headless themed sidebar panel shell.
+ *
+ * Renders the 240–248px wide panel: a background surface (colors.sidebarPanel),
+ * a right border (colors.border), an optional header slot, the item list
+ * (scrollable by default), and an optional footer slot.
+ *
+ * All content is delegated to the host via slots — only the chrome (bg, border,
+ * width) and the ScrollView wrapper are shared.
+ *
+ * ```tsx
+ * <Sidebar
+ *   header={
+ *     <SidebarHeader
+ *       leading={<SpaceSwitcher variant="sidebar" />}
+ *       actions={<>
+ *         <IconButton name="search" ... />
+ *         <IconButton name="plus" ... />
+ *       </>}
+ *     />
+ *   }
+ *   contentContainerStyle={{ paddingHorizontal: 8 }}
+ * >
+ *   <WorkObjects ... />
+ * </Sidebar>
+ * ```
+ */
+import React from 'react';
+import { ScrollView, View } from 'react-native';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+import { useOctoSpacesTheme } from '../theme/provider.js';
+
+export interface SidebarProps {
+  /** Header slot — render a {@link SidebarHeader} or custom content above the list. */
+  header?: React.ReactNode;
+  /** Footer slot — pinned below the scroll area. */
+  footer?: React.ReactNode;
+  /** The item list. Wrapped in a ScrollView unless `scrollable` is `false`. */
+  children: React.ReactNode;
+  /** Panel width in pixels. Defaults to `theme.layout.sidebarWidth ?? 248`. */
+  width?: number;
+  /**
+   * When `false`, children are rendered in a plain `View` instead of a `ScrollView`.
+   * Use when the host manages its own scroll (e.g. multiple independent lists).
+   * @default true
+   */
+  scrollable?: boolean;
+  /**
+   * Passed to the `ScrollView`'s `contentContainerStyle` (or to the body `View`
+   * style when `scrollable` is `false`).
+   */
+  contentContainerStyle?: StyleProp<ViewStyle>;
+  /**
+   * Override the panel background color.
+   * Defaults to `colors.sidebarPanel` from the injected theme.
+   */
+  background?: string;
+}
+
+export function Sidebar({
+  header,
+  footer,
+  children,
+  width,
+  scrollable = true,
+  contentContainerStyle,
+  background,
+}: SidebarProps) {
+  const theme = useOctoSpacesTheme();
+  const { colors, layout } = theme;
+
+  const panelWidth = width ?? (layout['sidebarWidth'] as number | undefined) ?? 248;
+  const bg = background ?? colors.sidebarPanel;
+
+  return (
+    <View
+      style={{
+        width: panelWidth,
+        backgroundColor: bg,
+        borderRightWidth: 1,
+        borderRightColor: colors.border,
+        flexDirection: 'column',
+      }}
+    >
+      {header ?? null}
+      {scrollable ? (
+        <ScrollView
+          style={{ flex: 1 }}
+          contentContainerStyle={contentContainerStyle ?? undefined}
+          showsVerticalScrollIndicator={false}
+        >
+          {children}
+        </ScrollView>
+      ) : (
+        <View style={[{ flex: 1 }, contentContainerStyle]}>{children}</View>
+      )}
+      {footer ?? null}
+    </View>
+  );
+}

package/src/sidebar/SidebarActionButton.tsx

@@ -0,0 +1,86 @@
+/**
+ * Headless themed icon-button primitive for sidebar action slots.
+ *
+ * Renders a square `Pressable` with hover/press wash from the injected theme.
+ * The icon is provided by the host app as a `ReactNode` — this keeps the package
+ * free of `@expo/vector-icons`, `Tooltip`, and keyboard-shortcut concerns.
+ *
+ * Host apps with richer icon buttons (OctoVault's `IconButton` has tooltips,
+ * keyboard-shortcut labels, and haptics) can slot those directly into
+ * `SidebarHeader.actions` instead — this primitive is for simpler headless
+ * consumers.
+ *
+ * ```tsx
+ * <SidebarActionButton
+ *   icon={<Icon name="search" size={15} color={theme.colors.textSecondary} />}
+ *   onPress={openSearch}
+ *   accessibilityLabel="Search"
+ * />
+ * ```
+ */
+import React, { useState } from 'react';
+import { Pressable as RNPressable } from 'react-native';
+import type { PressableProps, View as RNView } from 'react-native';
+
+import { useOctoSpacesTheme } from '../theme/provider.js';
+
+// React Native Web supports onMouseEnter/onMouseLeave.
+type HoverProps = { onMouseEnter?: () => void; onMouseLeave?: () => void };
+const Pressable = RNPressable as React.ForwardRefExoticComponent<
+  PressableProps & HoverProps & React.RefAttributes<RNView>
+>;
+
+export interface SidebarActionButtonProps {
+  /** Icon element to render — the host provides the icon component, size, and color. */
+  icon: React.ReactNode;
+  onPress: () => void;
+  accessibilityLabel: string;
+  /**
+   * Width and height of the pressable target in pixels.
+   * @default 32
+   */
+  size?: number;
+}
+
+export function SidebarActionButton({
+  icon,
+  onPress,
+  accessibilityLabel,
+  size = 32,
+}: SidebarActionButtonProps) {
+  const theme = useOctoSpacesTheme();
+  const { colors, radii } = theme;
+
+  const [hovered, setHovered] = useState(false);
+  const [pressed, setPressed] = useState(false);
+
+  const bg = pressed
+    ? (colors.primaryMuted ?? 'rgba(0,0,0,0.10)')
+    : hovered
+      ? (colors.primarySubtle ?? 'rgba(0,0,0,0.05)')
+      : 'transparent';
+
+  const radius = (radii['sm'] as number | undefined) ?? 4;
+
+  return (
+    <Pressable
+      onPress={onPress}
+      onPressIn={() => setPressed(true)}
+      onPressOut={() => setPressed(false)}
+      onMouseEnter={() => setHovered(true)}
+      onMouseLeave={() => setHovered(false)}
+      accessibilityRole="button"
+      accessibilityLabel={accessibilityLabel}
+      style={{
+        width: size,
+        height: size,
+        alignItems: 'center',
+        justifyContent: 'center',
+        borderRadius: radius,
+        backgroundColor: bg,
+      }}
+    >
+      {icon}
+    </Pressable>
+  );
+}

package/src/sidebar/SidebarHeader.tsx

@@ -0,0 +1,111 @@
+/**
+ * Headless themed sidebar header strip.
+ *
+ * Row 1: a `leading` slot (flex:1, typically a space selector or name) + an
+ * optional `actions` row (right-aligned command buttons). An optional `extra`
+ * slot below row 1 accepts additional controls (OctoChat uses this for its
+ * `ModeSwitcher` + jump-to search bar). An optional bottom hairline divider.
+ *
+ * ```tsx
+ * // OctoVault — space switcher + command icons
+ * <SidebarHeader
+ *   leading={<SpaceSwitcher variant="sidebar" />}
+ *   actions={<>
+ *     <IconButton name="search" onPress={openSearch} tooltip="Search" shortcut="⌘K" />
+ *     <IconButton name="plus"   onPress={newPage}    tooltip="New page" shortcut="⌘N" />
+ *     <IconButton name="sidebar" onPress={collapse}  tooltip="Hide sidebar" shortcut="⌘\\" />
+ *   </>}
+ * />
+ *
+ * // OctoChat — space menu + mode switcher + jump-to bar
+ * <SidebarHeader
+ *   leading={<Pressable onPress={onOpenSpaceMenu}>…</Pressable>}
+ *   extra={<><ModeSwitcher /><JumpToBar /></>}
+ *   divider
+ * />
+ * ```
+ */
+import React from 'react';
+import { StyleSheet, View } from 'react-native';
+import type { StyleProp, ViewStyle } from 'react-native';
+
+import { useOctoSpacesTheme } from '../theme/provider.js';
+
+export interface SidebarHeaderProps {
+  /** Leading content (flex:1) — typically the space selector / space name. */
+  leading: React.ReactNode;
+  /**
+   * Right-aligned action buttons row.
+   * OctoVault passes its own `IconButton` components here (with tooltips +
+   * keyboard shortcuts). For simpler headless consumers use `SidebarActionButton`.
+   */
+  actions?: React.ReactNode;
+  /**
+   * Extra slot rendered below the leading+actions row.
+   * Use for secondary controls like a mode switcher or a search bar.
+   */
+  extra?: React.ReactNode;
+  /**
+   * Render a hairline bottom divider in `colors.borderSubtle`.
+   * @default false
+   */
+  divider?: boolean;
+  /**
+   * Style applied to the outer container. Use to set host-specific padding,
+   * gap, background override, etc.
+   */
+  style?: StyleProp<ViewStyle>;
+}
+
+export function SidebarHeader({
+  leading,
+  actions,
+  extra,
+  divider = false,
+  style,
+}: SidebarHeaderProps) {
+  const theme = useOctoSpacesTheme();
+  const { colors } = theme;
+
+  return (
+    <View
+      style={[
+        styles.root,
+        style,
+        divider
+          ? {
+              borderBottomWidth: StyleSheet.hairlineWidth,
+              borderBottomColor: colors.borderSubtle,
+            }
+          : undefined,
+      ]}
+    >
+      {/* Row 1: leading + actions */}
+      <View style={styles.row}>
+        <View style={styles.leading}>{leading}</View>
+        {actions != null ? <View style={styles.actions}>{actions}</View> : null}
+      </View>
+      {/* Extra slot (ModeSwitcher, jump-to bar, etc.) */}
+      {extra != null ? <View>{extra}</View> : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: {
+    flexDirection: 'column',
+  },
+  row: {
+    flexDirection: 'row',
+    alignItems: 'center',
+  },
+  leading: {
+    flex: 1,
+    minWidth: 0,
+  },
+  actions: {
+    flexDirection: 'row',
+    alignItems: 'center',
+    flexShrink: 0,
+  },
+});

package/src/sidebar/SidebarItem.tsx

@@ -0,0 +1,148 @@
+/**
+ * Generic themed sidebar navigation row.
+ *
+ * The headless analog of `DiscoverRow` for the sidebar panel. Suitable for
+ * simple link-style rows (explore, threads, pinned, …). Complex item lists
+ * (OctoVault's `ObjectTree`, OctoChat's `RoomCategoryList`) use their own row
+ * components — this primitive is for straightforward nav items.
+ *
+ * Active rows are highlighted with `colors.sidebarActive`. Hovered rows receive
+ * a subtle `colors.primarySubtle` wash.
+ *
+ * ```tsx
+ * <SidebarItem
+ *   label="Threads"
+ *   icon={<Icon name="thread" size={15} color={colors.textSecondary} />}
+ *   active={threadsActive}
+ *   onPress={onOpenThreads}
+ * />
+ * ```
+ */
+import React, { useState } from 'react';
+import { Pressable as RNPressable, StyleSheet, Text, View } from 'react-native';
+import type { PressableProps, TextStyle, View as RNView } from 'react-native';
+
+import { useOctoSpacesTheme } from '../theme/provider.js';
+
+type HoverProps = { onMouseEnter?: () => void; onMouseLeave?: () => void };
+const Pressable = RNPressable as React.ForwardRefExoticComponent<
+  PressableProps & HoverProps & React.RefAttributes<RNView>
+>;
+
+export interface SidebarItemProps {
+  label: string;
+  /** Leading icon element — the host provides the icon component. */
+  icon?: React.ReactNode;
+  /** Highlight the row as the current destination. */
+  active?: boolean;
+  /** Badge shown at the trailing edge — a number or short string. */
+  badge?: number | string;
+  onPress: () => void;
+  onLongPress?: () => void;
+  /** Additional trailing element (e.g. an action button). */
+  trailing?: React.ReactNode;
+  /**
+   * Left indentation level for nested items. Each level adds 16 px.
+   * @default 0
+   */
+  indent?: number;
+}
+
+export function SidebarItem({
+  label,
+  icon,
+  active = false,
+  badge,
+  onPress,
+  onLongPress,
+  trailing,
+  indent = 0,
+}: SidebarItemProps) {
+  const theme = useOctoSpacesTheme();
+  const { colors, type: typeScale, fonts, spacing, radii } = theme;
+
+  const [hovered, setHovered] = useState(false);
+
+  const sp1 = (spacing['1'] as number | undefined) ?? 4;
+  const sp2 = (spacing['2'] as number | undefined) ?? 8;
+  const sp3 = (spacing['3'] as number | undefined) ?? 12;
+  const radSm = (radii['sm'] as number | undefined) ?? 4;
+  const indentPx = indent * 16;
+
+  const bg = active
+    ? colors.sidebarActive
+    : hovered
+      ? (colors.primarySubtle ?? 'rgba(0,0,0,0.04)')
+      : 'transparent';
+
+  const textColor = active ? colors.primary : colors.text;
+
+  return (
+    <Pressable
+      onPress={onPress}
+      onLongPress={onLongPress}
+      onMouseEnter={() => setHovered(true)}
+      onMouseLeave={() => setHovered(false)}
+      accessibilityRole="button"
+      accessibilityLabel={label}
+      style={{
+        flexDirection: 'row',
+        alignItems: 'center',
+        gap: sp2,
+        paddingVertical: sp1 + 2,
+        paddingLeft: sp3 + indentPx,
+        paddingRight: sp3,
+        borderRadius: radSm,
+        backgroundColor: bg,
+      }}
+    >
+      {icon != null ? <View style={styles.iconSlot}>{icon}</View> : null}
+      <Text
+        style={
+          {
+            flex: 1,
+            fontSize: typeScale['callout']?.size ?? 13,
+            lineHeight: typeScale['callout']?.lineHeight ?? 18,
+            fontWeight: active ? '600' : '400',
+            color: textColor,
+            fontFamily: fonts['body'] ?? undefined,
+          } as TextStyle
+        }
+        numberOfLines={1}
+      >
+        {label}
+      </Text>
+      {badge != null ? (
+        <View
+          style={{
+            minWidth: 16,
+            height: 16,
+            borderRadius: 8,
+            backgroundColor: active ? colors.primary : colors.textTertiary,
+            alignItems: 'center',
+            justifyContent: 'center',
+            paddingHorizontal: sp1,
+          }}
+        >
+          <Text
+            style={
+              {
+                fontSize: typeScale['micro']?.size ?? 10,
+                lineHeight: typeScale['micro']?.lineHeight ?? 14,
+                fontWeight: '700',
+                color: active ? colors.textOnPrimary : colors.textInverse,
+              } as TextStyle
+            }
+          >
+            {String(badge)}
+          </Text>
+        </View>
+      ) : null}
+      {trailing != null ? trailing : null}
+    </Pressable>
+  );
+}
+
+const styles = StyleSheet.create({
+  iconSlot: { width: 18, alignItems: 'center', justifyContent: 'center' },
+});

package/src/sidebar/index.ts

@@ -0,0 +1,11 @@
+export type { RailSpace, RailIconName } from './types.js';
+export type { SpacesRailProps } from './SpacesRail.js';
+export { SpacesRail } from './SpacesRail.js';
+export type { SidebarProps } from './Sidebar.js';
+export { Sidebar } from './Sidebar.js';
+export type { SidebarHeaderProps } from './SidebarHeader.js';
+export { SidebarHeader } from './SidebarHeader.js';
+export type { SidebarActionButtonProps } from './SidebarActionButton.js';
+export { SidebarActionButton } from './SidebarActionButton.js';
+export type { SidebarItemProps } from './SidebarItem.js';
+export { SidebarItem } from './SidebarItem.js';

package/src/theme/helpers.test.ts

@@ -18,6 +18,7 @@ const mockPalette: Palette = {
   surfaceModal: '#333',
   surfaceInput: '#444',
   sidebar: '#555',
+  sidebarPanel: '#55a',
   sidebarActive: '#666',
   border: '#777',
   borderSubtle: '#888',

package/src/theme/types.ts

@@ -27,6 +27,7 @@ export interface Palette {
   surfaceModal: string;
   surfaceInput: string;
   sidebar: string;
+  sidebarPanel: string;
   sidebarActive: string;
 
   // ── Borders + dividers ────────────────────────────────────────────────────