@drakkar.software/octospaces-ui 0.2.1 → 0.4.0

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-import React from 'react';
+import React, { ReactNode } from 'react';
+import { View, StyleProp, ViewStyle } from 'react-native';
 
 /**
  * Theme contract for `@drakkar.software/octospaces-ui`.
@@ -26,6 +27,7 @@ interface Palette {
     surfaceModal: string;
     surfaceInput: string;
     sidebar: string;
+    sidebarPanel: string;
     sidebarActive: string;
     border: string;
     borderSubtle: string;
@@ -349,4 +351,353 @@ interface DiscoverScreenProps {
 }
 declare function DiscoverScreen({ loadEntries, renderIcon, onOpen, title, emptyMessage, emptySearchMessage, searchEnabled, reloadRef, }: DiscoverScreenProps): 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 ShadowToken, type Shadows, type Spacing, type Swatches, type Theme, type TypeScale, type Typography, avatarTint, filterDiscoverEntries, focusRingStyle, glowShadow, paperBorder, presenceColor, sortDiscoverEntries, statusColor, swatch, useOctoSpacesTheme, verificationColor };
+/**
+ * Shared types for the SpacesRail component.
+ *
+ * Structurally compatible with `Space` from `@drakkar.software/octochat-sdk` /
+ * `@drakkar.software/octospaces-sdk` — apps can pass their domain objects directly
+ * without a runtime conversion step.
+ */
+/** A minimal space descriptor for the rail: id + display info + badge state. */
+interface RailSpace {
+    /** Unique space identifier. */
+    id: string;
+    /** Short display name or initials shown as a monogram when no image is available. */
+    short: string;
+    /** Optional image URI (data URI or URL) rendered as the tile background via
+     *  `SpacesRailProps.renderTileImage`. */
+    image?: string;
+    /** Unread-message count shown as a badge overlay. */
+    unread?: number;
+    /** Whether the space is muted (shows a mute-corner icon when `renderIcon` is provided). */
+    muted?: boolean;
+}
+/** Named icon slots injected into the rail via `SpacesRailProps.renderIcon`. */
+type RailIconName = 'dm' | 'lock' | 'mute' | 'add';
+
+/**
+ * Headless, abstractly-themed vertical spaces rail.
+ *
+ * The component reads the injected {@link Theme} via `useOctoSpacesTheme()` and
+ * delegates all app-specific concerns to props:
+ *
+ * - Icons are rendered by `renderIcon` (keeps `@expo/vector-icons` out of this package).
+ * - Space tile images are rendered by `renderTileImage` (keeps `expo-image` out too).
+ * - Unread badges are rendered by `renderBadge`.
+ * - The rail foot (account avatar + menu) is rendered by `renderFoot`.
+ * - Web drag-reorder is wired via the `useTileDnd` hook prop (see below).
+ *
+ * All React Native primitives used here ship with the `react-native` peer dep.
+ */
+
+interface SpacesRailProps {
+    /** The spaces to show in the scrollable column. */
+    spaces: RailSpace[];
+    /** The currently-active space id (or null / undefined for none). */
+    activeId?: string | null;
+    /** Called when the user selects a space tile. */
+    onSelect?: (id: string) => void;
+    /** Called when the user taps the "add" tile. */
+    onAdd?: () => void;
+    /** When provided, renders a leading DM-home tile. */
+    onSelectDms?: () => void;
+    /** Whether the DM-home tile is the active selection. */
+    dmsActive?: boolean;
+    /** Unread count for the DM-home tile badge. */
+    dmUnread?: number;
+    /** Accessibility label for the DM-home tile (default: "Direct messages"). */
+    dmLabel?: string;
+    /** Accessibility label for the add-space tile (default: "Create or join a space"). */
+    addLabel?: string;
+    /**
+     * Render a named icon at the given size and color. Used for the DM tile icon
+     * (`'dm'`), the E2EE lock corner (`'lock'`), the mute corner (`'mute'`),
+     * and the add tile icon (`'add'`). Return `null` to suppress the icon slot.
+     * If omitted, all icon slots render nothing.
+     */
+    renderIcon?: (name: RailIconName, size: number, color: string) => React.ReactNode;
+    /**
+     * Render an image filling the tile background. Only called when `space.image`
+     * is set. The component must fill its parent (`StyleSheet.absoluteFill` or
+     * equivalent). If omitted, the short-name monogram is shown instead.
+     */
+    renderTileImage?: (space: RailSpace) => React.ReactNode;
+    /**
+     * Render an unread badge. Only called when `space.unread > 0`.
+     * If omitted, badges are not shown.
+     */
+    renderBadge?: (count: number) => React.ReactNode;
+    /**
+     * When `true`, each tile shows a small E2EE-lock corner badge (bottom-right).
+     * Requires `renderIcon` to be provided (otherwise the corner renders nothing).
+     * Default: `false`.
+     */
+    showLockCorner?: boolean;
+    /**
+     * Render the pinned rail foot (e.g. the account avatar and popover).
+     * The host app owns this entirely — identity state stays out of the package.
+     */
+    renderFoot?: () => React.ReactNode;
+    /**
+     * **Hook injection for web drag-reorder.** When provided, each space tile is
+     * wrapped in a `DndTile` that calls `useTileDnd(spaceId)` unconditionally at
+     * the top of its render — treat this prop as a React hook and keep it stable
+     * for the lifetime of a `SpacesRail` mount (always provided or always absent).
+     * Omit on native / in apps that don't need DnD.
+     */
+    useTileDnd?: (spaceId: string) => {
+        ref?: React.Ref<View>;
+        over?: boolean;
+    };
+}
+/**
+ * Vertical spaces rail — a 64px-wide column of square space tiles, a DM-home tile,
+ * an add-space tile, and a pinned foot for the account widget.
+ *
+ * Styled entirely from the injected {@link Theme} via `useOctoSpacesTheme()`.
+ * All icons, images, badges, and the account foot are provided by the host app.
+ */
+declare function SpacesRail({ spaces, activeId, onSelect, onAdd, onSelectDms, dmsActive, dmUnread, dmLabel, addLabel, renderIcon, renderTileImage, renderBadge, showLockCorner, renderFoot, useTileDnd, }: SpacesRailProps): React.JSX.Element;
+
+/**
+ * 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;
+
+/**
+ * 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, SpacesRail, type SpacesRailProps, type Spacing, type Swatches, type Theme, type TypeScale, type Typography, avatarTint, filterDiscoverEntries, focusRingStyle, glowShadow, paperBorder, presenceColor, sortDiscoverEntries, statusColor, swatch, useOctoSpacesTheme, verificationColor };