@drakkar.software/octospaces-ui 0.3.0 → 0.4.1

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import React from 'react';
-import { View } from 'react-native';
+import React, { ReactNode } from 'react';
+import { View, StyleProp, ViewStyle } from 'react-native';
 
 /**
  * Theme contract for `@drakkar.software/octospaces-ui`.
@@ -27,6 +27,7 @@ interface Palette {
     surfaceModal: string;
     surfaceInput: string;
     sidebar: string;
+    sidebarPanel: string;
     sidebarActive: string;
     border: string;
     borderSubtle: string;
@@ -458,4 +459,354 @@ interface SpacesRailProps {
  */
 declare function SpacesRail({ spaces, activeId, onSelect, onAdd, onSelectDms, dmsActive, dmUnread, dmLabel, addLabel, renderIcon, renderTileImage, renderBadge, showLockCorner, renderFoot, useTileDnd, }: SpacesRailProps): React.JSX.Element;
 
-export { type ColorScheme, type DiscoverEntry, DiscoverList, type DiscoverListProps, DiscoverRow, type DiscoverRowProps, DiscoverScreen, type DiscoverScreenProps, type Easing, type Fonts, type LabelTracking, type Layers, type Layout, type Motion, type MotionToken, OctoSpacesThemeProvider, type OctoSpacesThemeProviderProps, type Opacity, type Palette, type Radii, type RailIconName, type RailSpace, type ShadowToken, type Shadows, SpacesRail, type SpacesRailProps, type Spacing, type Swatches, type Theme, type TypeScale, type Typography, avatarTint, filterDiscoverEntries, focusRingStyle, glowShadow, paperBorder, presenceColor, sortDiscoverEntries, statusColor, swatch, useOctoSpacesTheme, verificationColor };
+/**
+ * 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>
+ * ```
+ */
+
+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;
+}
+declare function Sidebar({ header, footer, children, width, scrollable, contentContainerStyle, background, }: SidebarProps): React.JSX.Element;
+
+/**
+ * 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
+ * />
+ * ```
+ */
+
+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>;
+}
+declare function SidebarHeader({ leading, actions, extra, divider, style, }: SidebarHeaderProps): React.JSX.Element;
+
+/**
+ * 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"
+ * />
+ * ```
+ */
+
+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;
+}
+declare function SidebarActionButton({ icon, onPress, accessibilityLabel, size, }: SidebarActionButtonProps): React.JSX.Element;
+
+/**
+ * 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}
+ * />
+ * ```
+ */
+
+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;
+}
+declare function SidebarItem({ label, icon, active, badge, onPress, onLongPress, trailing, indent, }: SidebarItemProps): React.JSX.Element;
+
+/**
+ * Headless themed space-switcher component.
+ *
+ * Renders a trigger button (active-space avatar + name + chevron) that opens a
+ * dropdown listing all spaces with per-row selection, a "join or create" action,
+ * optional space settings, and an app-provided footer slot (account section, etc.).
+ *
+ * The popup container (Popover on desktop, Sheet on mobile) is fully delegated to
+ * the host via `renderContainer` so this package stays free of modal dependencies.
+ * Avatars and icons are delegated via render-props for the same reason.
+ *
+ * @example
+ * ```tsx
+ * // OctoVault — sidebar variant with Popover container
+ * <SpaceSwitcher
+ *   spaces={spaces}
+ *   activeId={activeId}
+ *   onSelect={switchSpace}
+ *   onAdd={() => router.push('/join')}
+ *   onSettings={() => router.push(`/space/${activeId}`)}
+ *   variant="sidebar"
+ *   renderTriggerAvatar={(space, size) => (
+ *     <Avatar label={space?.short ?? ''} image={space?.image} size={size} />
+ *   )}
+ *   renderSpaceAvatar={(space, size) => (
+ *     <Avatar label={space.short ?? ''} image={space.image} size={size} />
+ *   )}
+ *   renderIcon={(name, size, color) => <Icon name={SWITCHER_ICON[name]} size={size} color={color} />}
+ *   renderContainer={({ isOpen, onClose, anchorRef, children }) => (
+ *     <>
+ *       <Popover visible={isOpen} onClose={onClose} anchorRef={anchorRef} placement="bottom-start" width={240}>
+ *         {children}
+ *       </Popover>
+ *     </>
+ *   )}
+ *   footerSlot={<AccountSwitcher onRequestClose={...} onViewProfile={...} />}
+ * />
+ * ```
+ */
+
+/** Structural space item — no SDK dependency. */
+interface SwitcherSpace {
+    id: string;
+    name: string;
+    /** 2-letter monogram used as avatar fallback. */
+    short?: string;
+    /** Uploaded space image URI; absent → host renders monogram. */
+    image?: string;
+}
+/** Icon name union for the switcher's built-in glyphs. */
+type SwitcherIconName = 'chevron-down' | 'check' | 'plus' | 'gear';
+interface SpaceSwitcherProps {
+    spaces: SwitcherSpace[];
+    activeId?: string | null;
+    /** Called when the user taps a space row. */
+    onSelect: (id: string) => void;
+    /** "Join or create a space" action. Omit to hide the row. */
+    onAdd?: () => void;
+    /** Override the add-row label. @default "Join or create a space" */
+    addLabel?: string;
+    /**
+     * "Space settings" action. Only shown when both `onSettings` and `activeId`
+     * are provided. Omit to hide.
+     */
+    onSettings?: () => void;
+    /** Override the settings-row label. @default "Space settings" */
+    settingsLabel?: string;
+    /**
+     * Visual variant:
+     * - `'sidebar'` — compact left-aligned trigger for the desktop sidebar header.
+     * - `'appbar'` — centered trigger for a phone app-bar title area.
+     */
+    variant: 'sidebar' | 'appbar';
+    /**
+     * Wraps the dropdown content in the host app's container (Popover / Sheet).
+     * Called with `{ isOpen, onClose, anchorRef, children }` — must render
+     * children inside an appropriate modal surface.
+     */
+    renderContainer: (props: {
+        isOpen: boolean;
+        onClose: () => void;
+        anchorRef: React.RefObject<View>;
+        children: React.ReactNode;
+    }) => React.ReactNode;
+    /**
+     * Render the active-space avatar inside the trigger button.
+     * Receives the active `SwitcherSpace` (or `null` when none) and a pixel size.
+     * Omit to render nothing in the avatar slot.
+     */
+    renderTriggerAvatar?: (space: SwitcherSpace | null, size: number) => React.ReactNode;
+    /**
+     * Render a space row's leading avatar.
+     * Receives the `SwitcherSpace` and a pixel size.
+     * Omit to render nothing in the leading slot.
+     */
+    renderSpaceAvatar?: (space: SwitcherSpace, size: number) => React.ReactNode;
+    /**
+     * Render an icon glyph. Name is one of `'chevron-down' | 'check' | 'plus' | 'gear'`.
+     * Omit to hide chevron, check, and action icons (spaces remain selectable).
+     */
+    renderIcon?: (name: SwitcherIconName, size: number, color: string) => React.ReactNode;
+    /**
+     * Footer rendered below the space list + action rows — use for account-switcher
+     * sections (with separator if needed). Fully app-owned.
+     */
+    footerSlot?: React.ReactNode;
+}
+declare function SpaceSwitcher({ spaces, activeId, onSelect, onAdd, addLabel, onSettings, settingsLabel, variant, renderContainer, renderTriggerAvatar, renderSpaceAvatar, renderIcon, footerSlot, }: SpaceSwitcherProps): React.JSX.Element;
+
+/**
+ * Full-screen scrim overlay that centers its content. Tapping the backdrop, the
+ * close button, the Escape key (web) or the hardware back (Android) dismisses it.
+ *
+ * All interactive chrome (close button, action buttons) is injected via render
+ * props so this package remains free of @expo/vector-icons, expo-image, and
+ * reanimated. The host app renders its own icon buttons and images.
+ *
+ * @example
+ * ```tsx
+ * import { Lightbox } from '@drakkar.software/octospaces-ui';
+ *
+ * <Lightbox
+ *   visible={zoomed}
+ *   onClose={() => setZoomed(false)}
+ *   renderCloseButton={(onClose) => (
+ *     <IconButton name="x" color={colors.onScrim} onPress={onClose} />
+ *   )}
+ *   renderActions={() => (
+ *     <IconButton name="share" color={colors.onScrim} onPress={handleShare} />
+ *   )}
+ * >
+ *   <Image source={{ uri }} style={{ width: w * 0.92, height: h * 0.82 }} />
+ * </Lightbox>
+ * ```
+ */
+
+interface LightboxProps {
+    visible: boolean;
+    onClose: () => void;
+    /** Centered content — the host renders the full-size image here. */
+    children: ReactNode;
+    /** Accessible label for the backdrop tap-to-close. Default: "Close preview". */
+    closeLabel?: string;
+    /**
+     * Render the close affordance pinned to the top-right corner.
+     * Receives `onClose` so the button can dismiss the overlay.
+     * If omitted, tapping the backdrop or hardware back still closes it.
+     */
+    renderCloseButton?: (onClose: () => void) => ReactNode;
+    /**
+     * Render additional action(s) pinned to the bottom-right corner,
+     * e.g. a save/share button. Return `null` to show nothing.
+     */
+    renderActions?: () => ReactNode;
+}
+/**
+ * Full-screen scrim overlay that centers its children. Headless: all buttons
+ * are injected via render props; the package has no icon or image dependencies.
+ *
+ * Dismissal: backdrop tap · `renderCloseButton` · hardware back (Android) ·
+ * Escape key (web).
+ */
+declare function Lightbox({ visible, onClose, children, closeLabel, renderCloseButton, renderActions, }: LightboxProps): React.JSX.Element;
+
+export { type ColorScheme, type DiscoverEntry, DiscoverList, type DiscoverListProps, DiscoverRow, type DiscoverRowProps, DiscoverScreen, type DiscoverScreenProps, type Easing, type Fonts, type LabelTracking, type Layers, type Layout, Lightbox, type LightboxProps, type Motion, type MotionToken, OctoSpacesThemeProvider, type OctoSpacesThemeProviderProps, type Opacity, type Palette, type Radii, type RailIconName, type RailSpace, type ShadowToken, type Shadows, Sidebar, SidebarActionButton, type SidebarActionButtonProps, SidebarHeader, type SidebarHeaderProps, SidebarItem, type SidebarItemProps, type SidebarProps, SpaceSwitcher, type SpaceSwitcherProps, SpacesRail, type SpacesRailProps, type Spacing, type Swatches, type SwitcherIconName, type SwitcherSpace, type Theme, type TypeScale, type Typography, avatarTint, filterDiscoverEntries, focusRingStyle, glowShadow, paperBorder, presenceColor, sortDiscoverEntries, statusColor, swatch, useOctoSpacesTheme, verificationColor };