@_tc/template-core 0.0.1-bate.46 → 0.0.1-bate.47

package/.skills/tc-component-usage-skills/reference/component-api.md

@@ -0,0 +1,801 @@
+# Component API Reference
+
+Complete props for every `@tc/ui-react` component.
+
+---
+
+## Button
+
+```typescript
+interface ButtonProps {
+  variant?: 'default' | 'primary' | 'dashed' | 'text' | 'link'
+  size?: 'sm' | 'md' | 'lg'
+  state?: 'danger' | 'ghost'
+  loading?: boolean
+  disabled?: boolean
+  leftIcon?: ReactNode
+  rightIcon?: ReactNode
+  noUnderline?: boolean       // only for link variant
+  className?: string
+  children?: ReactNode
+  onClick?: (e: MouseEvent) => void | Promise<void>
+}
+```
+
+`variant='link'` renders `<a>` tag. `SubmitButton` / `AsynchronousButton` auto-manage loading state on async onClick.
+
+### SubmitButton / AsynchronousButton
+
+```typescript
+interface SubmitButtonProps extends Omit<ButtonElementProps, 'onClick'> {
+  onClick?: (e: MouseEvent<HTMLButtonElement>) => Promise<void | boolean> | void
+}
+```
+
+Use `SubmitButton` or `AsynchronousButton` for async actions that should show loading and ignore repeated clicks while running. The old misspelled `SumbitButton` name should not be used in new code.
+
+---
+
+## Input
+
+```typescript
+interface InputProps extends Omit<React.InputHTMLAttributes<HTMLInputElement>, 'onChange' | 'size'> {
+  value?: string
+  defaultValue?: string
+  onChange?: (value: string, event: ChangeEvent<HTMLInputElement>) => void
+  allowClear?: boolean | { clearIcon: ReactNode }
+  addonAfter?: ReactNode
+  className?: string
+}
+```
+
+Note: `onChange` callback receives `(stringValue, event)` — two arguments, not one.
+
+---
+
+## InputNumber
+
+```typescript
+interface InputNumberProps {
+  value?: number
+  defaultValue?: number
+  onChange?: (value: number | undefined, event: ChangeEvent<HTMLInputElement>) => void
+  min?: number
+  max?: number
+  precision?: number            // decimal places
+  step?: number                  // default: 1
+  allowClear?: boolean | { clearIcon: ReactNode }
+  allowStep?: boolean            // show stepper buttons
+  disabled?: boolean
+  className?: string
+}
+```
+
+Invalid/empty input becomes `undefined`. Raw during focus, formatted on blur.
+
+---
+
+## Textarea
+
+```typescript
+interface TextareaProps {
+  value?: string
+  defaultValue?: string
+  onChange?: (value: string, event: ChangeEvent) => void
+  maxLength?: number             // default: 500
+  showCount?: boolean            // default: true
+  rows?: number
+  disabled?: boolean
+  className?: string
+}
+```
+
+Character counter overlays bottom-right.
+
+---
+
+## Select
+
+```typescript
+interface SelectOption {
+  label: ReactNode
+  value: string | number
+  searchText?: string           // optional separate search text
+}
+
+interface SelectProps {
+  options: SelectOption[]
+  value?: string | number
+  defaultValue?: string | number
+  placeholder?: string
+  onChange?: (value: string | number | undefined) => void
+  className?: string
+  disabled?: boolean
+  clearable?: boolean            // default: true
+  searchable?: boolean           // default: true
+  getPopupContainer?: 'parent' | (() => HTMLElement)
+}
+```
+
+`onChange` receives `undefined` on clear. When `getPopupContainer='parent'`, parent must be non-static positioned.
+
+---
+
+## Checkbox
+
+```typescript
+interface CheckboxProps {
+  checked?: boolean
+  defaultChecked?: boolean
+  indeterminate?: boolean
+  value?: boolean                 // controlled alias for checked
+  onChange?: (checked: boolean) => void
+  disabled?: boolean
+  className?: string
+  children?: ReactNode
+}
+```
+
+---
+
+## Switch
+
+```typescript
+interface SwitchProps {
+  checked?: boolean
+  defaultChecked?: boolean
+  onChange?: (checked: boolean) => void
+  disabled?: boolean
+  className?: string
+}
+```
+
+---
+
+## Radio / RadioGroup
+
+```typescript
+interface RadioGroupProps {
+  value?: string
+  defaultValue?: string
+  onChange?: (value: string) => void
+  direction?: 'horizontal' | 'vertical'
+  className?: string
+  children?: ReactNode
+}
+
+interface RadioProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'type' | 'children'> {
+  label?: ReactNode
+  disabled?: boolean
+  className?: string
+}
+```
+
+Use `<RadioGroup>` with `<Radio value="..." label="..." />`. Radio auto-detects parent context; group selection only handles string values.
+
+---
+
+## DatePicker
+
+```typescript
+type ModeType = 'single' | 'range'
+
+interface DatePickerProps {
+  mode?: ModeType                 // default: 'single'
+  value?: Date | DateRange | [string, string] | string
+  defaultValue?: DateValue
+  format?: string                 // default: 'yyyy-MM-dd' (adds 'HH:mm' when showTime)
+  placeholder?: string
+  disabled?: boolean
+  allowClear?: boolean            // default: true
+  showTime?: boolean              // default: false
+  onChange?: (value?: DateChangeStrValue, date?: Dates) => void
+  disabledDate?: (current: Date) => boolean
+  className?: string
+  locale?: Partial<DateLocaleConfig>
+  quickRanges?: QuickRangePreset[]
+  getPopupContainer?: () => HTMLElement
+}
+```
+
+Accepts flexible value formats (Date, DateRange, string tuples, YYYY-MM-DD strings). Range mode has read-only input.
+
+---
+
+## TreeSelect
+
+```typescript
+interface TreeNode {
+  id: string | number
+  name: string
+  desctext?: string
+  children?: TreeNode[]
+}
+
+interface TreeSelectProps {
+  data: TreeNode[]
+  value?: (string | number)[]    // controlled checked keys
+  onChange?: (keys: { checked: (string | number)[], indeterminate: (string | number)[] }) => void
+  labelField?: 'name' | 'desctext'
+  checkable?: boolean             // default: true
+  className?: string
+}
+```
+
+Tri-state checkboxes with cascading selection (parent ↔ children).
+
+---
+
+## Upload
+
+### FileUpload
+
+```typescript
+interface FileUploadProps {
+  inputRef?: RefObject<HTMLInputElement | null>
+  accept?: string                 // default: '*'
+  multiple?: boolean
+  onChange?: (event: ChangeEvent<HTMLInputElement>) => void
+  selectLabel: ReactNode
+  labelClassName?: string
+  showClear?: boolean
+  onClear?: () => void
+  clearLabel?: ReactNode
+}
+```
+
+### ImageUpload
+
+```typescript
+interface ImageUploadProps {
+  accept?: string                 // default: '.jpg,.png'
+  maxCount?: number               // default: 1
+  value?: string[]                // controlled URLs
+  onChange?: (urls: string[]) => void
+  beforeChange?: (file: File) => boolean | void
+}
+```
+
+Uses `URL.createObjectURL` for previews; revokes on remove/unmount.
+
+---
+
+## Form / FormItem / SchemaForm
+
+### Form
+
+```typescript
+interface FormProps<T> extends Omit<RcFormProps<T>, 'component'> {
+  className?: string
+  children?: ReactNode
+}
+```
+
+Thin wrapper around rc-field-form's `RcForm` with `component="form"`.
+
+### FormItem
+
+```typescript
+interface FormItemProps<T> extends Omit<FieldProps, 'children'> {
+  className?: string
+  label?: ReactNode
+  labelClassName?: string
+  required?: boolean              // display indicator only
+  children?: ReactNode | ((value: T, onChange: (v: T) => void, meta: {...}) => ReactNode)
+  errorClassName?: string
+  showError?: boolean
+  layout?: 'vertical' | 'horizontal'
+}
+```
+
+Children can be a render function. Auto-clones children to inject `value`/`onChange`.
+
+### SchemaForm
+
+```typescript
+interface SchemaFormProps<T> {
+  form?: FormInstance<T>
+  getForm?: (formInstance: FormInstance<T>) => void
+  schemas: FormFieldSchema<T>[]
+  className?: string
+  onFinish?: (values: T) => void
+  onFinishFailed?: (errorInfo: any) => void
+  initialValues?: T
+  layout?: 'vertical' | 'horizontal'       // default: 'vertical'
+  fieldLayout?: 'vertical' | 'horizontal'   // default: 'vertical'
+  footerButtons?: boolean | ReactNode       // default: true
+  submitText?: ReactNode
+  cancelText?: ReactNode
+  onCancel?: () => void                     // default: form.resetFields()
+  buttonClassName?: string
+  submitButtonProps?: Omit<ButtonElementProps, 'type' | 'onClick' | 'children'>
+  cancelButtonProps?: Omit<ButtonElementProps, 'onClick' | 'children'>
+  preserve?: boolean                        // default: false
+}
+```
+
+**Important:** In `horizontal` layout, `footerButtons` are NOT auto-rendered. UI-library built-in types: `input`, `inputNumber`, `select`, `textarea`, `switch`, `date`, `checkbox`. TemplateCore also registers framework type `asyncSelect`. App types are extensible via `@tc/scalability/SchemaForm/data`.
+
+---
+
+## DataTable (generic `<T>`)
+
+```typescript
+interface DataTableProps<T> {
+  columns: TableColumnDef<T>[]
+  data: T[]
+  rowKey?: keyof T | ((record: T, index: number) => string | number)  // default: 'id'
+  rowSelection?: RowSelection<T>
+  pagination?: PaginationProps
+  loading?: boolean
+  defaultColumnWidth?: number     // default: 100
+}
+```
+
+Internal pagination (pageSize: 10) when no external pagination prop. Action columns are auto-sticky right. Loading shows skeleton overlay. Empty state shows no-result image.
+
+### RowSelection
+
+```typescript
+interface RowSelection<T> {
+  selectedRowKeys?: Array<string | number>
+  defaultSelectedRowKeys?: Array<string | number>
+  onChange?: (selectedRowKeys: Array<string | number>, selectedRows: T[], isAll: boolean) => void
+  isAll?: boolean
+  beforeCheckboxNode?: ReactNode
+}
+```
+
+### TableColumnDef
+
+```typescript
+// ColumnDefForKey: maps to a data key
+// ColumnDefAction: defines action column with actions: DropdownItem[]
+
+// Key fields on column definition:
+{
+  key: string
+  title: string
+  dataIndex: string
+  width?: string
+  fixed?: 'left' | 'right'
+  isAction?: boolean
+  actions?: DropdownItem[] | ((value, record, index) => DropdownItem[])
+  actionOverflow?: 'auto' | 'dropdown' | 'inline'
+  render?: (value, record, index) => ReactNode
+}
+```
+
+Action columns are detected by `key: 'action'` or `isAction: true`, and render via `ActionBtn` with `'auto'` | `'dropdown'` | `'inline'` overflow modes.
+
+---
+
+## TableSearch (generic `<T>`)
+
+```typescript
+interface TableSearchProps<T> {
+  schemas: TableSearchSchema<T>[]       // FormFieldSchema[] with optional isPermanent
+  onSearch?: (values: T) => void
+  onReset?: () => void
+  exportMenuItems?: DropdownItem[]
+  onExport?: (exportType: ExportType, searchData: T) => void
+  renderActionBtnArea?: () => ReactNode
+  additionalButtons?: ReactNode
+  btnConfig?: Partial<{ export, collapse, expandIcon, expand, reset, search }>
+  expandBoundaries?: number             // default: 4
+  defaultExpand?: boolean               // default: true
+}
+```
+
+Fields not marked `isPermanent` are hidden when collapsed. Uses `Search` internally.
+
+---
+
+## Modal
+
+```typescript
+interface ModalProps {
+  open?: boolean                  // default: false
+  onClose?: () => void
+  title?: ReactNode
+  children?: ReactNode
+  footer?: ReactNode
+  className?: string
+  contentClassName?: string
+  mask?: boolean                  // default: true
+  maskClosable?: boolean          // default: true
+  lockScroll?: boolean            // default: true
+  closable?: boolean              // default: true
+  width?: number | string         // default: 520
+  centered?: boolean              // default: true (false → mt-[10vh])
+  zIndex?: number                 // default: 1000
+  renderNode?: HTMLElement | (() => HTMLElement)
+  keyboard?: boolean              // default: true
+}
+```
+
+### Modal Function API (imperative)
+
+```typescript
+modal.open(config: ModalConfig): string      // returns id
+modal.confirm(config: ConfirmConfig): string // async onOk supported
+modal.close(id: string): void
+modal.closeAll(): void
+```
+
+---
+
+## Drawer
+
+```typescript
+type DrawerPlacement = 'top' | 'right' | 'bottom' | 'left'
+
+interface DrawerProps {
+  open?: boolean
+  onClose?: () => void
+  title?: ReactNode
+  children?: ReactNode
+  footer?: ReactNode
+  className?: string
+  contentClassName?: string
+  mask?: boolean                  // default: true
+  maskClosable?: boolean          // default: true
+  lockScroll?: boolean            // default: true
+  closable?: boolean              // default: true
+  placement?: DrawerPlacement     // default: 'right'
+  width?: number | string         // default: 420 (for left/right)
+  height?: number | string        // default: 360 (for top/bottom)
+  zIndex?: number                 // default: 1000
+  renderNode?: HTMLElement | (() => HTMLElement)
+  keyboard?: boolean              // default: true
+}
+```
+
+Uses `requestAnimationFrame` for mount/unmount animation lifecycle (320ms).
+
+---
+
+## ConfirmDialog
+
+```typescript
+interface ConfirmDialogProps {
+  open: boolean
+  title?: string
+  content: string
+  okText?: string
+  cancelText?: string
+  loading?: boolean
+  onOk: () => void | Promise<void>
+  onCancel: () => void
+}
+```
+
+Wraps `Modal` with width: 450 and auto async-supporting ok button.
+
+---
+
+## Popup
+
+```typescript
+interface PopupProps {
+  open: boolean
+  anchorRef: RefObject<HTMLElement | null>
+  children: ReactNode             // popup panel content
+  placement?: DropdownPlacement   // default: 'bottom-end'
+  offset?: number                 // default: 8
+  keepMounted?: boolean
+  closeOnClickOutside?: boolean
+  closeOnEscape?: boolean
+  matchAnchorWidth?: boolean
+  onOpenChange?: (open: boolean) => void
+  className?: string
+  container?: HTMLElement
+}
+```
+
+Low-level positioned popup. For click-triggered menus, prefer `Dropdown`; for hints, prefer `Tooltip`.
+
+---
+
+## Dropdown
+
+```typescript
+interface DropdownItem {
+  key: string
+  label?: ReactNode
+  icon?: ReactNode
+  danger?: boolean
+  onClick?: () => void
+  // Or custom render:
+  render?: (item, context: { onClick: () => void; close: () => void }) => ReactNode
+}
+
+interface DropdownProps {
+  items: DropdownItem[]
+  children: ReactNode
+  placement?: DropdownPlacement
+  className?: string
+  getPopupContainer?: () => HTMLElement
+}
+```
+
+---
+
+## Tooltip
+
+```typescript
+interface TooltipProps {
+  content: ReactNode
+  children: ReactElement
+  placement?: 'top' | 'bottom' | 'left' | 'right'
+  visible?: boolean
+  className?: string
+}
+```
+
+---
+
+## Menu
+
+```typescript
+interface MenuProps {
+  mode?: 'top' | 'left'           // default: 'left'
+  expandTrigger?: 'hover' | 'click' // default: 'click'
+  expandMode?: 'accordion' | 'multiple' // default: 'accordion'
+  selectedKey?: string
+  defaultSelectedKey?: string
+  onSelect?: (key: string) => void
+  items?: MenuItemData[]          // declarative API (alternative to children)
+  children?: ReactNode
+  className?: string
+  collapsed?: boolean
+  defaultCollapsed?: boolean
+  onCollapse?: (collapsed: boolean) => void
+  collapsedWidth?: number         // default: 64
+  collapsedLabelTooltip?: boolean // default: true
+}
+```
+
+Compound: `<Menu>` + `<Menu.Item>` + `<Menu.SubMenu>` + `<Menu.CollapseToggle>`.
+
+### MenuItem
+
+```typescript
+interface MenuItemProps {
+  eventKey: string
+  icon?: ReactNode
+  disabled?: boolean
+  danger?: boolean
+  onClick?: () => void
+  children?: ReactNode
+}
+```
+
+### SubMenu
+
+```typescript
+interface SubMenuProps {
+  eventKey: string
+  label: ReactNode
+  icon?: ReactNode
+  disabled?: boolean
+  popup?: boolean
+  children?: ReactNode
+}
+```
+
+---
+
+## Layout
+
+```typescript
+interface LayoutProps {
+  header?: ReactNode
+  sidebar?: ReactNode
+  children?: ReactNode
+  footer?: ReactNode
+  className?: string
+}
+```
+
+Flexbox: header/footer shrink-0, sidebar w-60 shrink-0, main flex-1 overflow-y-auto.
+
+---
+
+## Tabs
+
+```typescript
+interface TabItem {
+  key: string
+  label: ReactNode
+  disabled?: boolean
+}
+
+interface TabsProps {
+  items: TabItem[]
+  activeKey?: string
+  defaultActiveKey?: string
+  onChange?: (key: string) => void
+  className?: string
+}
+```
+
+Tab bar only — no built-in tab panels. Active tab has bottom border accent.
+
+---
+
+## Breadcrumb
+
+Compound: `<Breadcrumb>`, `<BreadcrumbList>`, `<BreadcrumbItem>`, `<BreadcrumbLink>`, `<BreadcrumbPage>`, `<BreadcrumbSeparator>`, `<BreadcrumbEllipsis>`.
+
+`SimpleBreadcrumb`: Application-level wrapper with router navigate and closable tabs.
+
+---
+
+## Pagination
+
+```typescript
+interface PaginationProps {
+  current: number
+  pageSize: number
+  total: number
+  onChange: (page: number) => void
+  onPageSizeChange?: (pageSize: number) => void
+  pageSizeOptions?: number[]      // default: [10, 20, 50, 100]
+  className?: string
+}
+```
+
+Smart ellipsis (max 7 pages shown), page size selector via Select.
+
+---
+
+## ImagePreview
+
+### ImagePreviewController
+
+```typescript
+interface ImagePreviewControllerProps {
+  open: boolean
+  images: string[]
+  initialIndex?: number           // default: 0
+  onClose: () => void
+}
+```
+
+Features: zoom (0.2x–5x), drag-to-pan, rotate, flip, keyboard nav.
+
+### PreviewImage
+
+```typescript
+interface PreviewImageProps extends MOmit<ImagePreviewControllerProps, 'open' | 'onClose'> {
+  onClose?: () => void
+  thumbSize?: number | string     // default: 80
+  direction?: 'horizontal' | 'vertical'
+}
+```
+
+Thumbnail grid → click to open full controller.
+
+---
+
+## Card
+
+```typescript
+interface CardProps {
+  header?: ReactNode
+  footer?: ReactNode
+  children?: ReactNode
+  className?: string
+}
+```
+
+---
+
+## Message (Function API)
+
+```typescript
+message.success(content: ReactNode, config?: MessageConfig): void
+message.error(content: ReactNode, config?: MessageConfig): void
+message.warning(content: ReactNode, config?: MessageConfig): void
+message.info(content: ReactNode, config?: MessageConfig): void
+```
+
+Max 5 visible messages.
+
+---
+
+## Notification
+
+```typescript
+interface NotificationProps {
+  type: 'info' | 'success' | 'warning' | 'error'
+  title: ReactNode
+  message?: ReactNode
+  duration?: number
+  closable?: boolean
+}
+```
+
+---
+
+## Loading
+
+```typescript
+interface LoadingProps {
+  size?: 'sm' | 'md' | 'lg'
+  text?: ReactNode
+  className?: string
+}
+
+interface LoadingIndicatorProps {
+  size?: 'sm' | 'md' | 'lg'
+  className?: string
+}
+```
+
+`Loading` renders the shared spinner with optional text. `LoadingIndicator` is the icon-only spinner used by compact surfaces such as `Button.loading`.
+
+---
+
+## Skeleton
+
+```typescript
+interface SkeletonProps {
+  mode?: 'pageloading' | 'tableloading' | 'componentsloading'
+  rows?: number
+  showTitle?: boolean
+  showActions?: boolean
+}
+```
+
+---
+
+## Label
+
+```typescript
+interface LabelProps {
+  layout?: 'vertical' | 'horizontal'
+  labelWidth?: number | string
+  labelAlign?: 'left' | 'right' | 'center'
+  required?: boolean
+  children?: ReactNode
+}
+```
+
+---
+
+## Overlay (internal, used by Modal/Drawer)
+
+```typescript
+interface OverlayProps {
+  visible: boolean
+  mask?: boolean
+  maskClosable?: boolean
+  lockScroll?: boolean
+  keyboard?: boolean
+  zIndex?: number
+  children?: ReactNode
+  renderNode?: HTMLElement | (() => HTMLElement)
+  onClose?: () => void
+  className?: string
+}
+```
+
+Reference-counted body scroll lock across multiple overlays.
+
+---
+
+## Search (internal)
+
+```typescript
+interface SearchProps<T> {
+  schemas: FormFieldSchema<T>[]
+  getForm?: (formInstance: FormInstance<T>) => void
+  onSearch?: (values: T) => void
+  className?: string
+  // ... other SchemaForm props
+}
+```
+
+Wraps `SchemaForm` with `layout='horizontal'`, `preserve=true`, `footerButtons={false}`.