@liiift-studio/mac-os9-ui 0.2.21 → 0.2.24

package/dist/types/components/FolderList/FolderList.d.ts

@@ -1,12 +1,57 @@
 import React from 'react';
 import { WindowProps } from '../Window/Window';
-import { ListColumn, ListItem } from '../ListView/ListView';
-export interface FolderListProps extends Omit<WindowProps, 'children'> {
+import { WindowPosition } from '../../types';
+import { ListColumn, ListItem, RowRenderState, RowDefaultProps, CellRenderState, HeaderCellRenderState, HeaderCellDefaultProps } from '../ListView/ListView';
+/**
+ * Classes for targeting FolderList sub-elements
+ */
+export interface FolderListClasses {
+    /** Root window container */
+    root?: string;
+    /** Window component */
+    window?: string;
+    /** Title bar */
+    titleBar?: string;
+    /** ListView container */
+    listView?: string;
+    /** ListView header */
+    header?: string;
+    /** ListView header cell */
+    headerCell?: string;
+    /** ListView body */
+    body?: string;
+    /** ListView row */
+    row?: string;
+    /** ListView cell */
+    cell?: string;
+}
+export interface FolderListProps extends Omit<WindowProps, 'children' | 'classes'> {
     /**
      * Column definitions for the list
      * @default [{ key: 'name', label: 'Name' }, { key: 'modified', label: 'Date Modified' }, { key: 'size', label: 'Size' }]
      */
     columns?: ListColumn[];
+    /**
+     * Whether the folder list window can be dragged by its title bar
+     * Window starts in normal flow and becomes absolutely positioned when dragged
+     * @default false
+     */
+    draggable?: boolean;
+    /**
+     * Initial position for draggable folder lists (uncontrolled)
+     * Only used when draggable is true
+     */
+    defaultPosition?: WindowPosition;
+    /**
+     * Controlled position for draggable folder lists
+     * Only used when draggable is true
+     */
+    position?: WindowPosition;
+    /**
+     * Callback when folder list position changes (during drag)
+     * Only called when draggable is true
+     */
+    onPositionChange?: (position: WindowPosition) => void;
     /**
      * Items to display in the list
      */
@@ -24,9 +69,13 @@ export interface FolderListProps extends Omit<WindowProps, 'children'> {
      */
     onItemOpen?: (item: ListItem) => void;
     /**
-     * Callback when mouse enters an item
+     * Callback when mouse enters an item (row-level)
      */
     onItemMouseEnter?: (item: ListItem) => void;
+    /**
+     * Callback when mouse leaves an item (row-level)
+     */
+    onItemMouseLeave?: (item: ListItem) => void;
     /**
      * Callback when column header is clicked for sorting
      */
@@ -40,6 +89,47 @@ export interface FolderListProps extends Omit<WindowProps, 'children'> {
      * @default 400
      */
     listHeight?: number | string;
+    /**
+     * Custom classes for targeting sub-elements
+     */
+    classes?: FolderListClasses;
+    /**
+     * Override row rendering
+     * @param item - The list item
+     * @param state - Row state (selected, hovered, index)
+     * @param defaultProps - Props to spread on custom element for accessibility
+     * @returns Custom row element (fully replaces default)
+     */
+    renderRow?: (item: ListItem, state: RowRenderState, defaultProps: RowDefaultProps) => React.ReactNode;
+    /**
+     * Override cell rendering
+     * @param value - Cell value (item[columnKey])
+     * @param item - Full item object
+     * @param column - Column definition
+     * @param state - Cell state (hovered, selected row, indices)
+     * @returns Custom cell content (fully replaces default)
+     */
+    renderCell?: (value: any, item: ListItem, column: ListColumn, state: CellRenderState) => React.ReactNode;
+    /**
+     * Override header cell rendering
+     * @param column - Column definition
+     * @param state - Header state (sorted, direction)
+     * @param defaultProps - Props to spread on custom element
+     * @returns Custom header cell element (fully replaces default)
+     */
+    renderHeaderCell?: (column: ListColumn, state: HeaderCellRenderState, defaultProps: HeaderCellDefaultProps) => React.ReactNode;
+    /**
+     * Callback when a cell is clicked
+     */
+    onCellClick?: (item: ListItem, column: ListColumn, event: React.MouseEvent) => void;
+    /**
+     * Callback when mouse enters a cell
+     */
+    onCellMouseEnter?: (item: ListItem, column: ListColumn) => void;
+    /**
+     * Callback when mouse leaves a cell
+     */
+    onCellMouseLeave?: (item: ListItem, column: ListColumn) => void;
 }
 /**
  * Mac OS 9 style FolderList component
@@ -49,6 +139,7 @@ export interface FolderListProps extends Omit<WindowProps, 'children'> {
  *
  * @example
  * ```tsx
+ * // Basic folder list
  * <FolderList
  *   title="My Documents"
  *   items={[
@@ -58,8 +149,14 @@ export interface FolderListProps extends Omit<WindowProps, 'children'> {
  *   selectedIds={['1']}
  *   onSelectionChange={(ids) => console.log('Selected:', ids)}
  *   onItemOpen={(item) => console.log('Open:', item.name)}
- *   onItemMouseEnter={(item) => console.log('Hovering:', item.name)}
- *   onMouseEnter={(e) => console.log('Mouse entered folder list')}
+ * />
+ *
+ * // Draggable folder list
+ * <FolderList
+ *   title="My Documents"
+ *   items={items}
+ *   draggable
+ *   defaultPosition={{ x: 100, y: 100 }}
  * />
  * ```
  */

package/dist/types/components/FolderList/index.d.ts

@@ -1,2 +1,2 @@
 export { FolderList, FolderList as default } from './FolderList';
-export type { FolderListProps } from './FolderList';
+export type { FolderListProps, FolderListClasses } from './FolderList';

package/dist/types/components/ListView/ListView.d.ts

@@ -33,6 +33,84 @@ export interface ListItem {
      */
     icon?: React.ReactNode;
 }
+/**
+ * Classes for targeting ListView sub-elements
+ */
+export interface ListViewClasses {
+    /** Root container */
+    root?: string;
+    /** Header row container */
+    header?: string;
+    /** Individual header cell */
+    headerCell?: string;
+    /** Body container (scrollable area) */
+    body?: string;
+    /** Individual row */
+    row?: string;
+    /** Individual cell */
+    cell?: string;
+}
+/**
+ * Row render prop state
+ */
+export interface RowRenderState {
+    /** Whether this row is selected */
+    isSelected: boolean;
+    /** Whether this row is being hovered */
+    isHovered: boolean;
+    /** Row index in the list */
+    index: number;
+}
+/**
+ * Row render prop default props
+ * Spread these on your custom element for accessibility and behavior
+ */
+export interface RowDefaultProps {
+    key: string;
+    className: string;
+    onClick: (e: React.MouseEvent) => void;
+    onDoubleClick: () => void;
+    onMouseEnter: () => void;
+    onMouseLeave: () => void;
+    'data-selected': boolean;
+    'data-index': number;
+    'data-item-id': string;
+}
+/**
+ * Cell render prop state
+ */
+export interface CellRenderState {
+    /** Whether this cell is being hovered */
+    isHovered: boolean;
+    /** Whether the row containing this cell is selected */
+    isRowSelected: boolean;
+    /** Column index */
+    columnIndex: number;
+    /** Row index */
+    rowIndex: number;
+}
+/**
+ * Header cell render prop state
+ */
+export interface HeaderCellRenderState {
+    /** Whether this column is currently sorted */
+    isSorted: boolean;
+    /** Current sort direction if sorted */
+    sortDirection?: 'asc' | 'desc';
+}
+/**
+ * Header cell render prop default props
+ */
+export interface HeaderCellDefaultProps {
+    key: string;
+    className: string;
+    style: React.CSSProperties;
+    onClick: () => void;
+    'data-column': string;
+    'data-sortable': boolean;
+    'data-sorted'?: boolean;
+    'data-sort-direction'?: 'asc' | 'desc';
+}
 export interface ListViewProps {
     /**
      * Column definitions
@@ -55,9 +133,13 @@ export interface ListViewProps {
      */
     onItemOpen?: (item: ListItem) => void;
     /**
-     * Callback when mouse enters an item
+     * Callback when mouse enters an item (row-level)
      */
     onItemMouseEnter?: (item: ListItem) => void;
+    /**
+     * Callback when mouse leaves an item (row-level)
+     */
+    onItemMouseLeave?: (item: ListItem) => void;
     /**
      * Callback when column is clicked for sorting
      */
@@ -70,6 +152,47 @@ export interface ListViewProps {
      * Height of the list view
      */
     height?: number | string;
+    /**
+     * Custom classes for targeting sub-elements
+     */
+    classes?: ListViewClasses;
+    /**
+     * Override row rendering
+     * @param item - The list item
+     * @param state - Row state (selected, hovered, index)
+     * @param defaultProps - Props to spread on custom element for accessibility
+     * @returns Custom row element (fully replaces default)
+     */
+    renderRow?: (item: ListItem, state: RowRenderState, defaultProps: RowDefaultProps) => React.ReactNode;
+    /**
+     * Override cell rendering
+     * @param value - Cell value (item[columnKey])
+     * @param item - Full item object
+     * @param column - Column definition
+     * @param state - Cell state (hovered, selected row, indices)
+     * @returns Custom cell content (fully replaces default)
+     */
+    renderCell?: (value: any, item: ListItem, column: ListColumn, state: CellRenderState) => React.ReactNode;
+    /**
+     * Override header cell rendering
+     * @param column - Column definition
+     * @param state - Header state (sorted, direction)
+     * @param defaultProps - Props to spread on custom element
+     * @returns Custom header cell element (fully replaces default)
+     */
+    renderHeaderCell?: (column: ListColumn, state: HeaderCellRenderState, defaultProps: HeaderCellDefaultProps) => React.ReactNode;
+    /**
+     * Callback when a cell is clicked
+     */
+    onCellClick?: (item: ListItem, column: ListColumn, event: React.MouseEvent) => void;
+    /**
+     * Callback when mouse enters a cell
+     */
+    onCellMouseEnter?: (item: ListItem, column: ListColumn) => void;
+    /**
+     * Callback when mouse leaves a cell
+     */
+    onCellMouseLeave?: (item: ListItem, column: ListColumn) => void;
 }
 /**
  * Mac OS 9 style ListView component

package/dist/types/components/ListView/index.d.ts

@@ -1,2 +1,2 @@
 export { ListView, ListView as default } from './ListView';
-export type { ListViewProps, ListColumn, ListItem } from './ListView';
+export type { ListViewProps, ListColumn, ListItem, ListViewClasses, RowRenderState, RowDefaultProps, CellRenderState, HeaderCellRenderState, HeaderCellDefaultProps } from './ListView';

package/dist/types/components/MenuBar/MenuDropdown.d.ts

@@ -0,0 +1,36 @@
+import React from 'react';
+export interface MenuDropdownProps {
+    /**
+     * Menu label (displayed in the menu bar/button)
+     */
+    label: React.ReactNode;
+    /**
+     * Menu items (content of the dropdown)
+     */
+    items: React.ReactNode;
+    /**
+     * Whether the menu is disabled
+     * @default false
+     */
+    disabled?: boolean;
+    /**
+     * Custom class name for the menu container
+     */
+    className?: string;
+    /**
+     * Custom class name for menu dropdown
+     */
+    dropdownClassName?: string;
+    /**
+     * Alignment of the dropdown menu
+     * @default 'left'
+     */
+    align?: 'left' | 'right';
+}
+/**
+ * Mac OS 9 style MenuDropdown component
+ *
+ * A standalone dropdown menu that shares the styling of the MenuBar.
+ * Useful for placing menus in the status area (rightContent) or other parts of the app.
+ */
+export declare const MenuDropdown: React.FC<MenuDropdownProps>;

package/dist/types/components/MenuBar/MenuItem.d.ts

@@ -53,6 +53,10 @@ export interface MenuItemProps {
      * @default false
      */
     hasSubmenu?: boolean;
+    /**
+     * Submenu items
+     */
+    items?: React.ReactNode;
 }
 /**
  * Mac OS 9 style MenuItem component

package/dist/types/components/MenuBar/index.d.ts

@@ -1,3 +1,4 @@
 export { MenuBar, type MenuBarProps, type Menu } from './MenuBar';
 export { MenuItem, type MenuItemProps } from './MenuItem';
+export { MenuDropdown, type MenuDropdownProps } from './MenuDropdown';
 export { default } from './MenuBar';

package/dist/types/components/Window/Window.d.ts

@@ -1,4 +1,22 @@
 import React from 'react';
+import { WindowPosition } from '../../types';
+/**
+ * Classes for targeting Window sub-elements
+ */
+export interface WindowClasses {
+    /** Root container */
+    root?: string;
+    /** Title bar */
+    titleBar?: string;
+    /** Title text */
+    titleText?: string;
+    /** Window controls container */
+    controls?: string;
+    /** Individual control button */
+    controlButton?: string;
+    /** Content area */
+    content?: string;
+}
 export interface WindowProps {
     /**
      * Window content
@@ -36,6 +54,10 @@ export interface WindowProps {
      * Custom class name for the content area
      */
     contentClassName?: string;
+    /**
+     * Custom classes for targeting sub-elements
+     */
+    classes?: WindowClasses;
     /**
      * Whether to show window controls (close, minimize, maximize)
      * @default true
@@ -62,6 +84,27 @@ export interface WindowProps {
      * @default false
      */
     resizable?: boolean;
+    /**
+     * Whether the window can be dragged by its title bar
+     * Window starts in normal flow and becomes absolutely positioned when dragged
+     * @default false
+     */
+    draggable?: boolean;
+    /**
+     * Initial position for draggable windows (uncontrolled)
+     * Only used when draggable is true
+     */
+    defaultPosition?: WindowPosition;
+    /**
+     * Controlled position for draggable windows
+     * Only used when draggable is true
+     */
+    position?: WindowPosition;
+    /**
+     * Callback when window position changes (during drag)
+     * Only called when draggable is true
+     */
+    onPositionChange?: (position: WindowPosition) => void;
 }
 /**
  * Mac OS 9 style Window component
@@ -74,6 +117,7 @@ export interface WindowProps {
  * - Active/inactive states
  * - Composable with custom TitleBar component
  * - Flexible sizing
+ * - Draggable windows (optional) - drag by title bar
  *
  * @example
  * ```tsx
@@ -95,6 +139,31 @@ export interface WindowProps {
  * >
  *   <p>Content</p>
  * </Window>
+ *
+ * // Draggable window (uncontrolled)
+ * <Window title="Draggable" draggable>
+ *   <p>Drag me by the title bar!</p>
+ * </Window>
+ *
+ * // Draggable window with initial position
+ * <Window
+ *   title="Positioned"
+ *   draggable
+ *   defaultPosition={{ x: 100, y: 100 }}
+ * >
+ *   <p>Starts at a specific position</p>
+ * </Window>
+ *
+ * // Controlled draggable window
+ * const [pos, setPos] = useState({ x: 0, y: 0 });
+ * <Window
+ *   title="Controlled"
+ *   draggable
+ *   position={pos}
+ *   onPositionChange={setPos}
+ * >
+ *   <p>Parent controls position</p>
+ * </Window>
  * ```
  */
 export declare const Window: React.ForwardRefExoticComponent<WindowProps & React.RefAttributes<HTMLDivElement>>;

package/dist/types/components/Window/index.d.ts

@@ -1,2 +1,2 @@
-export { Window, type WindowProps } from './Window';
+export { Window, type WindowProps, type WindowClasses } from './Window';
 export { default } from './Window';

package/dist/types/index.d.ts

@@ -7,12 +7,13 @@ export { Radio, type RadioProps } from './components/Radio';
 export { TextField, type TextFieldProps } from './components/TextField';
 export { Select, type SelectProps, type SelectOption } from './components/Select';
 export { Tabs, TabPanel, type TabsProps, type TabPanelProps } from './components/Tabs';
-export { Window, type WindowProps } from './components/Window';
+export { Window, type WindowProps, type WindowClasses } from './components/Window';
 export { Dialog, type DialogProps } from './components/Dialog';
-export { MenuBar, MenuItem, type MenuBarProps, type MenuItemProps, type Menu } from './components/MenuBar';
+export { MenuBar, MenuItem, MenuDropdown, type MenuBarProps, type MenuItemProps, type Menu, type MenuDropdownProps } from './components/MenuBar';
 export { Scrollbar, type ScrollbarProps } from './components/Scrollbar';
-export { ListView, type ListViewProps, type ListColumn, type ListItem } from './components/ListView';
-export { FolderList, type FolderListProps } from './components/FolderList';
+export { ListView, type ListViewProps, type ListColumn, type ListItem, type ListViewClasses, type RowRenderState, type RowDefaultProps, type CellRenderState, type HeaderCellRenderState, type HeaderCellDefaultProps } from './components/ListView';
+export { FolderList, type FolderListProps, type FolderListClasses } from './components/FolderList';
 export * from './components/Icon/categories';
 export * from './tokens';
+export { mergeClasses, createClassBuilder } from './utils/classNames';
 export type * from './types';

package/dist/types/types/index.d.ts

@@ -1,14 +1,41 @@
+/**
+ * Generic classes object for targeting sub-elements within components
+ * Components extend this with specific element keys
+ */
+export interface ComponentClasses {
+    root?: string;
+    [key: string]: string | undefined;
+}
 /**
  * Base component props that all components should extend
+ * @template TClasses - Specific classes type for the component
  */
-export interface BaseComponentProps {
-    /** Additional CSS class name */
+export interface BaseComponentProps<TClasses extends ComponentClasses = ComponentClasses> {
+    /** Additional CSS class name for root element */
     className?: string;
     /** Inline styles */
     style?: React.CSSProperties;
+    /** Custom classes for targeting sub-elements */
+    classes?: TClasses;
     /** Test ID for testing purposes */
     'data-testid'?: string;
 }
+/**
+ * Common render state interface for render prop patterns
+ * Provides information about element state for conditional rendering
+ */
+export interface RenderState {
+    /** Whether the element is being hovered */
+    isHovered?: boolean;
+    /** Whether the element is selected */
+    isSelected?: boolean;
+    /** Whether the element is in active state (e.g., pressed) */
+    isActive?: boolean;
+    /** Whether the element has keyboard focus */
+    isFocused?: boolean;
+    /** Whether the element is disabled */
+    isDisabled?: boolean;
+}
 /**
  * Common variant types for Mac OS 9 components
  */
@@ -21,6 +48,13 @@ export type Size = 'small' | 'medium' | 'large';
  * Common state types
  */
 export type State = 'default' | 'hover' | 'active' | 'disabled' | 'focused';
+/**
+ * Window position for draggable windows
+ */
+export interface WindowPosition {
+    x: number;
+    y: number;
+}
 /**
  * Component ref types
  */

package/dist/types/utils/classNames.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Merges multiple class names into a single string
+ * Filters out undefined, null, false, and empty strings
+ *
+ * @param classes - Class names to merge
+ * @returns Merged class name string
+ *
+ * @example
+ * ```ts
+ * mergeClasses('base', isActive && 'active', undefined, 'custom')
+ * // Returns: "base active custom"
+ * ```
+ */
+export declare const mergeClasses: (...classes: (string | undefined | false | null)[]) => string;
+/**
+ * Creates a class name builder function with a base class
+ * Useful for component-level class management
+ *
+ * @param baseClass - Base class name
+ * @returns Function that merges additional classes with base
+ *
+ * @example
+ * ```ts
+ * const cn = createClassBuilder('button');
+ * cn('primary', isDisabled && 'disabled')
+ * // Returns: "button primary disabled"
+ * ```
+ */
+export declare const createClassBuilder: (baseClass: string) => (...additionalClasses: (string | undefined | false | null)[]) => string;

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@liiift-studio/mac-os9-ui",
-	"version": "0.2.21",
+	"version": "0.2.24",
 	"description": "A pixel-perfect Mac OS 9 UI component library for React and TypeScript",
 	"private": false,
 	"sideEffects": [