@simplysm/solid 13.0.98 → 13.0.100

package/docs/data.md

@@ -1,125 +1,167 @@
 # Data Components
 
-Source: `src/components/data/**/*.tsx`
+Source: `src/components/data/**`
 
-## Table
+## `Table`
 
-Styled HTML table with border-separated cells.
+Simple HTML table component with border and padding styles.
 
-```ts
-interface TableProps extends JSX.HTMLAttributes<HTMLTableElement> {
-  inset?: boolean;  // borderless style for embedding
+```typescript
+export interface TableProps extends JSX.HTMLAttributes<HTMLTableElement> {
+  inset?: boolean;
 }
 ```
 
+| Prop | Type | Description |
+|------|------|-------------|
+| `inset` | `boolean` | Remove outer border and rounded corners |
+
 ### Sub-components
 
-- **`Table.Row`** -- `<tr>` element. Extends `JSX.HTMLAttributes<HTMLTableRowElement>`.
-- **`Table.HeaderCell`** -- `<th>` element with bold text and muted background. Extends `JSX.ThHTMLAttributes<HTMLTableCellElement>`.
-- **`Table.Cell`** -- `<td>` element with borders. Extends `JSX.TdHTMLAttributes<HTMLTableCellElement>`.
+- **`Table.Row`** -- Table row (`<tr>`)
+- **`Table.HeaderCell`** -- Header cell (`<th>`) with bold text and muted background
+- **`Table.Cell`** -- Body cell (`<td>`)
+
+---
 
-## List
+## `List`
 
-Vertical list container with nesting support via `ListContext`.
+Container component for list items with tree-view keyboard navigation (Space/Enter, ArrowUp/Down, ArrowLeft/Right, Home/End).
 
-```ts
-interface ListProps extends JSX.HTMLAttributes<HTMLDivElement> {
-  inset?: boolean;  // borderless style
+```typescript
+export interface ListProps extends JSX.HTMLAttributes<HTMLDivElement> {
+  inset?: boolean;
 }
 ```
 
-Uses `ListContext` to track nesting level for indentation.
+| Prop | Type | Description |
+|------|------|-------------|
+| `inset` | `boolean` | Transparent background, no outer border |
+
+### Sub-components
+
+- **`List.Item`** -- Interactive list item (see `ListItem` below)
+
+---
+
+## `ListContext`
 
-### ListContext
+Context for tracking nesting level in nested lists.
 
-```ts
-interface ListContextValue {
+```typescript
+export interface ListContextValue {
   level: number;
 }
 
-const ListContext: Context<ListContextValue>;  // default: { level: 0 }
-function useListContext(): ListContextValue;
+export const ListContext: Context<ListContextValue>;
+export const useListContext: () => ListContextValue;
 ```
 
-### ListItem
+---
 
-Interactive list item with selection, expansion, and ripple support.
+## `ListItem.styles`
 
-```ts
-interface ListItemProps extends Omit<JSX.HTMLAttributes<HTMLButtonElement>, "onClick"> {
-  selected?: boolean;
-  disabled?: boolean;
-  readOnly?: boolean;
-  size?: ComponentSize;
-  open?: boolean;
-  onOpenChange?: (open: boolean) => void;
-  onClick?: (e: MouseEvent) => void;
-}
-```
+Shared style constants for list items.
+
+| Export | Type | Description |
+|--------|------|-------------|
+| `listItemBaseClass` | `string` | Base item styles |
+| `listItemSizeClasses` | `Record<ComponentSize, string>` | Size-specific padding |
+| `listItemSelectedClass` | `string` | Selected state styles |
+| `listItemDisabledClass` | `string` | Disabled state styles |
+| `listItemReadonlyClass` | `string` | Read-only state styles |
+| `listItemIndentGuideClass` | `string` | Indent guide line styles |
+| `listItemBasePadLeft` | `Record<ComponentSize, number>` | Base left padding per size (rem) |
+| `LIST_ITEM_INDENT_SIZE` | `number` | Indent size per nesting level (1.5 rem) |
+| `listItemContentClass` | `string` | Item content area styles |
+| `getListItemSelectedIconClass` | `(selected: boolean) => string` | Selection icon color |
 
-- **`ListItem.Children`** -- Nested content rendered inside a `Collapse`. Children are wrapped in a nested `List`.
+---
 
-## Pagination
+## `Pagination`
 
-Page navigation control with first/prev/next/last buttons.
+Page navigation component with first/prev/next/last buttons and page number buttons.
 
-```ts
-interface PaginationProps extends JSX.HTMLAttributes<HTMLElement> {
+```typescript
+export interface PaginationProps extends JSX.HTMLAttributes<HTMLElement> {
   page: number;
   onPageChange?: (page: number) => void;
   totalPageCount: number;
-  displayPageCount?: number;  // default: 10
+  displayPageCount?: number;
   size?: ComponentSize;
 }
 ```
 
-## DataSheet
+| Prop | Type | Description |
+|------|------|-------------|
+| `page` | `number` | Current page (1-based) |
+| `onPageChange` | `(page: number) => void` | Page change callback |
+| `totalPageCount` | `number` | Total number of pages |
+| `displayPageCount` | `number` | Visible page buttons. Default: `10` |
+| `size` | `ComponentSize` | Button size |
 
-Spreadsheet-like data grid with sorting, selection, expansion, reorder, column resize, and configuration.
+---
 
-```ts
-interface DataSheetProps<TItem> {
-  items: TItem[];
-  getItemKey: (item: TItem) => string | number | undefined;
-  getItemChildren?: (item: TItem, index: number, depth: number) => TItem[] | undefined;
+## `DataSheet`
+
+Feature-rich data grid with sorting, pagination, selection, tree expansion, column resizing/reordering, fixed columns, and config persistence.
+
+```typescript
+export interface DataSheetProps<TItem> {
+  items?: TItem[];
   storageKey?: string;
+  hideConfigBar?: boolean;
   inset?: boolean;
+  contentStyle?: JSX.CSSProperties | string;
+  sorts?: SortingDef[];
+  onSortsChange?: (sorts: SortingDef[]) => void;
+  autoSort?: boolean;
   page?: number;
   onPageChange?: (page: number) => void;
   totalPageCount?: number;
-  sorts?: SortingDef[];
-  onSortsChange?: (sorts: SortingDef[]) => void;
+  pageSize?: number;
+  displayPageCount?: number;
   selectionMode?: "single" | "multiple";
-  selectedKeys?: (string | number)[];
-  onSelectedKeysChange?: (keys: (string | number)[]) => void;
-  onSelect?: (result: { items: TItem[]; keys: (string | number)[] }) => void;
-  onReorder?: (event: DataSheetReorderEvent<TItem>) => void;
+  selection?: TItem[];
+  onSelectionChange?: (items: TItem[]) => void;
+  autoSelect?: boolean;
+  isItemSelectable?: (item: TItem) => boolean | string;
+  expandedItems?: TItem[];
+  onExpandedItemsChange?: (items: TItem[]) => void;
+  itemChildren?: (item: TItem, index: number) => TItem[] | undefined;
+  cellClass?: (item: TItem, colKey: string) => string | undefined;
+  cellStyle?: (item: TItem, colKey: string) => string | undefined;
+  onItemsReorder?: (event: DataSheetReorderEvent<TItem>) => void;
   class?: string;
-  style?: JSX.CSSProperties;
   children: JSX.Element;
 }
 ```
 
-### Sub-components
-
-- **`DataSheet.Column<TItem>`** -- Column definition.
+### `DataSheetColumnProps`
 
-```ts
-interface DataSheetColumnProps<TItem> {
+```typescript
+export interface DataSheetColumnProps<TItem> {
   key: string;
   header?: string | string[];
-  width?: string;
-  minWidth?: string;
+  headerContent?: () => JSX.Element;
+  headerStyle?: string;
+  summary?: () => JSX.Element;
+  tooltip?: string;
   fixed?: boolean;
-  align?: "left" | "center" | "right";
+  hidden?: boolean;
+  collapse?: boolean;
+  width?: string;
+  class?: string;
   sortable?: boolean;
-  sortKey?: string;
   resizable?: boolean;
-  summary?: (items: TItem[]) => JSX.Element;
   children: (ctx: DataSheetCellContext<TItem>) => JSX.Element;
 }
+```
+
+### `DataSheetCellContext`
 
-interface DataSheetCellContext<TItem> {
+```typescript
+export interface DataSheetCellContext<TItem> {
   item: TItem;
   index: number;
   row: number;
@@ -127,90 +169,174 @@ interface DataSheetCellContext<TItem> {
 }
 ```
 
-### DataSheet.Config
+### `SortingDef`
 
-Column visibility and order configuration dialog, persisted via storage.
-
-```ts
-interface DataSheetConfig {
-  columns: DataSheetConfigColumn[];
+```typescript
+export interface SortingDef {
+  key: string;
+  desc: boolean;
 }
+```
 
-interface DataSheetConfigColumn {
-  key: string;
-  hidden?: boolean;
-  width?: string;
+### `DataSheetReorderEvent`
+
+```typescript
+export interface DataSheetReorderEvent<TItem> {
+  item: TItem;
+  targetItem: TItem;
+  position: DataSheetDragPosition;
 }
+
+export type DataSheetDragPosition = "before" | "after" | "inside";
 ```
 
-### Related Types
+### `DataSheetConfig` / `DataSheetConfigColumn`
 
-```ts
-interface SortingDef {
-  key: string;
-  desc: boolean;
+```typescript
+export interface DataSheetConfig {
+  columnRecord?: Partial<Record<string, DataSheetConfigColumn>>;
 }
 
-interface DataSheetReorderEvent<TItem> {
-  item: TItem;
-  position: "before" | "after" | "inside";
-  target: TItem;
+export interface DataSheetConfigColumn {
+  fixed?: boolean;
+  width?: string;
+  displayOrder?: number;
+  hidden?: boolean;
 }
 ```
 
-## Calendar
+### `FlatItem`
 
-Month calendar displaying items on date cells.
+```typescript
+export interface FlatItem<TItem> {
+  item: TItem;
+  index: number;
+  row: number;
+  depth: number;
+  hasChildren: boolean;
+  parent?: TItem;
+}
+```
 
-```ts
-interface CalendarProps<TValue> extends Omit<JSX.HTMLAttributes<HTMLDivElement>, "children"> {
-  year: number;
-  month: number;
-  onYearChange?: (year: number) => void;
-  onMonthChange?: (month: number) => void;
-  items?: TValue[];
-  getItemDate?: (item: TValue) => DateOnly;
-  renderItem?: (item: TValue, index: number) => JSX.Element;
-  onDateClick?: (date: DateOnly) => void;
-  size?: ComponentSize;
-  class?: string;
-  style?: JSX.CSSProperties;
+---
+
+## `DataSheet.styles`
+
+Shared style constants for DataSheet rendering. Key exports:
+
+| Export | Description |
+|--------|-------------|
+| `dataSheetContainerClass` | Container class |
+| `tableClass` | Table element class |
+| `thClass` / `tdClass` | Header/body cell classes |
+| `summaryThClass` | Summary row header class |
+| `sortableThClass` | Sortable header class |
+| `fixedClass` / `fixedLastClass` | Fixed column classes |
+| `resizerClass` | Column resize handle class |
+| `resizeIndicatorClass` | Resize drag indicator class |
+| `featureThClass` / `featureTdClass` | Feature column classes |
+| `expandToggleClass` | Expand toggle button class |
+| `selectSingleClass` | Single select icon class |
+| `reorderHandleClass` | Drag reorder handle class |
+| `reorderIndicatorClass` | Reorder drag indicator class |
+| `toolbarClass` | Toolbar class |
+| `trRowClass` | Body row class with hover/selected overlays |
+| `configButtonClass` | Settings button class |
+
+---
+
+## `Calendar`
+
+Monthly calendar grid displaying items by date.
+
+```typescript
+export interface CalendarProps<TValue> extends Omit<
+  JSX.HTMLAttributes<HTMLTableElement>,
+  "children"
+> {
+  items: TValue[];
+  getItemDate: (item: TValue, index: number) => DateOnly;
+  renderItem: (item: TValue, index: number) => JSX.Element;
+  yearMonth?: DateOnly;
+  onYearMonthChange?: (value: DateOnly) => void;
+  weekStartDay?: number;
+  minDaysInFirstWeek?: number;
 }
 ```
 
-## Kanban
+| Prop | Type | Description |
+|------|------|-------------|
+| `items` | `TValue[]` | Data items to display |
+| `getItemDate` | `(item, index) => DateOnly` | Extract date from item |
+| `renderItem` | `(item, index) => JSX.Element` | Render item content |
+| `yearMonth` | `DateOnly` | Displayed month |
+| `onYearMonthChange` | `(value: DateOnly) => void` | Month change callback |
+| `weekStartDay` | `number` | Week start day (0=Sun). Default: `0` |
+| `minDaysInFirstWeek` | `number` | Min days in first week. Default: `1` |
 
-Kanban board with drag-and-drop cards between lanes.
+---
 
-```ts
-interface KanbanProps<TCardValue, TLaneValue> extends Omit<JSX.HTMLAttributes<HTMLDivElement>, "children"> {
-  onDrop?: (info: KanbanDropInfo<TLaneValue, TCardValue>) => void;
-  children: JSX.Element;
+## `Kanban`
+
+Drag-and-drop kanban board with lanes, cards, and multi-select support.
+
+### Types
+
+```typescript
+export interface KanbanCardRef<TLaneValue, TCardValue> {
+  value: TCardValue | undefined;
+  laneValue: TLaneValue | undefined;
+  heightOnDrag: number;
 }
 
-interface KanbanDropInfo<TLaneValue, TCardValue> {
-  card: KanbanCardRef<TLaneValue, TCardValue>;
-  target: KanbanDropTarget<TCardValue>;
+export interface KanbanDropInfo<TLaneValue, TCardValue> {
+  sourceValue?: TCardValue;
+  targetLaneValue?: TLaneValue;
+  targetCardValue?: TCardValue;
+  position?: "before" | "after";
 }
-```
 
-### Sub-components
+export interface KanbanDropTarget<TCardValue> {
+  element: HTMLElement;
+  value: TCardValue | undefined;
+  position: "before" | "after";
+}
 
-- **`Kanban.Lane<TLaneValue>`** -- Lane container.
+export interface KanbanCardProps<TCardValue = unknown> {
+  value?: TCardValue;
+  draggable?: boolean;
+  selectable?: boolean;
+  contentClass?: string;
+  children?: JSX.Element;
+}
+```
 
-```ts
-interface KanbanLaneProps<TLaneValue> extends Omit<JSX.HTMLAttributes<HTMLDivElement>, "children"> {
-  value: TLaneValue;
-  header?: JSX.Element;
-  children: JSX.Element;
+### `KanbanContextValue`
+
+```typescript
+export interface KanbanContextValue<TLaneValue, TCardValue> {
+  dragCard: Accessor<KanbanCardRef<TLaneValue, TCardValue> | undefined>;
+  setDragCard: Setter<KanbanCardRef<TLaneValue, TCardValue> | undefined>;
+  onDropTo: (targetLaneValue, targetCardValue, position) => void;
+  selectedValues: Accessor<TCardValue[]>;
+  setSelectedValues: (updater) => void;
+  toggleSelection: (value: TCardValue) => void;
 }
 ```
 
-- **`Kanban.Card<TCardValue>`** -- Draggable card.
+### `KanbanLaneContextValue`
 
-```ts
-interface KanbanCardProps<TCardValue> extends Omit<JSX.HTMLAttributes<HTMLDivElement>, "children"> {
-  value: TCardValue;
-  children: JSX.Element;
+```typescript
+export interface KanbanLaneContextValue<TLaneValue, TCardValue> {
+  value: Accessor<TLaneValue | undefined>;
+  dropTarget: Accessor<KanbanDropTarget<TCardValue> | undefined>;
+  setDropTarget: (target) => void;
+  registerCard: (id, info) => void;
+  unregisterCard: (id) => void;
 }
 ```
+
+### Hooks
+
+- **`useKanbanContext()`** -- Access board-level context
+- **`useKanbanLaneContext()`** -- Access lane-level context