@multicomma/arkcn 0.1.2 → 0.1.3

package/src/components/ui/scheduler.tsx

@@ -57,14 +57,20 @@ type CreateState = { start: Date; end: Date } | null
 type SchedulerContextValue = {
   date: Date
   setDate: (date: Date) => void
+  /** Controlled view: `day`, `week`, or `month`. */
   view: SchedulerView
   setView: (view: SchedulerView) => void
   range: { start: Date; end: Date }
   days: Date[]
+  /** First day of the week, 0 for Sunday. */
   weekStartsOn: 0 | 1 | 2 | 3 | 4 | 5 | 6
+  /** Pixels per hour in the time grid. */
   hourHeight: number
+  /** Snap and keyboard step in minutes. */
   slotMinutes: number
+  /** First hour shown in the time grid. */
   minHour: number
+  /** Last hour shown in the time grid. */
   maxHour: number
   editable: boolean
   interaction: Interaction | null
@@ -98,7 +104,9 @@ function visibleRange(date: Date, view: SchedulerView, weekStartsOn: SchedulerCo
   if (view === "day") return { start: startOfDay(date), end: startOfDay(date) }
   if (view === "week") return { start: startOfWeek(date, { weekStartsOn }), end: endOfWeek(date, { weekStartsOn }) }
   return {
+    /** Event start. */
     start: startOfWeek(startOfMonth(date), { weekStartsOn }),
+    /** Event end. */
     end: endOfWeek(endOfMonth(date), { weekStartsOn }),
   }
 }
@@ -127,17 +135,28 @@ function Scheduler({
   ...props
 }: Omit<React.ComponentProps<"div">, "onChange"> & {
   date?: Date
+  /** Initial anchor date when uncontrolled. */
   defaultDate?: Date
+  /** Called when the anchor date changes. */
   onDateChange?: (date: Date) => void
+  /** Controlled view: `day`, `week`, or `month`. */
   view?: SchedulerView
+  /** Initial view when uncontrolled. */
   defaultView?: SchedulerView
+  /** Called when the view changes. */
   onViewChange?: (view: SchedulerView) => void
+  /** First day of the week, 0 for Sunday. */
   weekStartsOn?: SchedulerContextValue["weekStartsOn"]
+  /** Pixels per hour in the time grid. */
   hourHeight?: number
+  /** Snap and keyboard step in minutes. */
   slotMinutes?: number
+  /** First hour shown in the time grid. */
   minHour?: number
+  /** Last hour shown in the time grid. */
   maxHour?: number
   editable?: boolean
+  /** Called with `{ id, start, end }` snapped to `slotMinutes` after a move, resize, or keyboard change. */
   onEventChange?: (change: SchedulerEventChange) => void
   /** Drag on empty time (or a month cell click) proposes a new event. */
   onCreate?: (range: { start: Date; end: Date; allDay?: boolean }) => void
@@ -268,7 +287,9 @@ function Scheduler({
       const column = (pointer.currentTarget as HTMLElement).getBoundingClientRect()
       const originMin = yToMinutes(pointer.clientY - column.top)
       let current: NonNullable<CreateState> = {
+        /** Event start. */
         start: withMinutes(day, originMin),
+        /** Event end. */
         end: withMinutes(day, originMin + slotMinutes),
       }
       let dragged = false
@@ -352,14 +373,18 @@ function Scheduler({
       const next =
         part === "end"
           ? {
+              /** Event start. */
               start: event.start,
+              /** Event end. */
               end: addMinutes(
                 event.end,
                 Math.max(deltaMinutes, slotMinutes - differenceInMinutes(event.end, event.start))
               ),
             }
           : {
+              /** Event start. */
               start: addDays(addMinutes(event.start, deltaMinutes), deltaDays),
+              /** Event end. */
               end: addDays(addMinutes(event.end, deltaMinutes), deltaDays),
             }
       onEventChangeRef.current?.({ id: event.id, ...next })
@@ -772,6 +797,7 @@ function SchedulerDayColumn<T extends EventLike>({
   ...props
 }: Omit<React.ComponentProps<"div">, "children"> & {
   date: Date
+  /** Events shown in this column; overlaps are laid out side by side. */
   events: T[]
   children: (event: T) => React.ReactNode
 }) {

package/src/components/ui/separator.tsx

@@ -12,6 +12,7 @@ function Separator({
   ...props
 }: React.ComponentProps<"div"> & {
   orientation?: "horizontal" | "vertical"
+  /** Hide the separator from assistive technology. */
   decorative?: boolean
 }) {
   return (

package/src/components/ui/sidebar.tsx

@@ -141,6 +141,7 @@ function Sidebar({
 }: React.ComponentProps<"div"> & {
   side?: "left" | "right"
   variant?: "sidebar" | "floating" | "inset"
+  /** Collapse mode: `offcanvas`, `icon`, or `none`. */
   collapsible?: "offcanvas" | "icon" | "none"
 }) {
   const { isMobile, state, openMobile, setOpenMobile } = useSidebar()
@@ -473,6 +474,7 @@ function SidebarMenuButton({
   ...props
 }: React.ComponentProps<"button"> & {
   asChild?: boolean
+  /** Marks the current item. */
   isActive?: boolean
   tooltip?: string | React.ComponentProps<typeof TooltipContent>
 } & VariantProps<typeof sidebarMenuButtonVariants>) {
@@ -516,6 +518,7 @@ function SidebarMenuAction({
   ...props
 }: React.ComponentProps<"button"> & {
   asChild?: boolean
+  /** Only reveal the action when the item is hovered or focused. */
   showOnHover?: boolean
 }) {
   const Comp = ark.button
@@ -555,6 +558,7 @@ function SidebarMenuSkeleton({
   showIcon = false,
   ...props
 }: React.ComponentProps<"div"> & {
+  /** Render an icon placeholder in the skeleton. */
   showIcon?: boolean
 }) {
   // Random width between 50 to 90%.
@@ -617,6 +621,7 @@ function SidebarMenuSubButton({
 }: React.ComponentProps<"a"> & {
   asChild?: boolean
   size?: "sm" | "md"
+  /** Marks the current item. */
   isActive?: boolean
 }) {
   const Comp = ark.a

package/src/components/ui/toggle-group.tsx

@@ -9,12 +9,14 @@ import { toggleVariants } from "@/components/ui/toggle"
 
 const ToggleGroupVariantContext = React.createContext<
   VariantProps<typeof toggleVariants> & {
+    /** Gap between items; 0 joins them into one control. */
     spacing?: number
     orientation?: "horizontal" | "vertical"
   }
 >({
   size: "default",
   variant: "default",
+  /** Gap between items; 0 joins them into one control. */
   spacing: 2,
   orientation: "horizontal",
 })
@@ -29,6 +31,7 @@ function ToggleGroup({
   ...props
 }: React.ComponentProps<typeof ToggleGroupPrimitive.Root> &
   VariantProps<typeof toggleVariants> & {
+    /** Gap between items; 0 joins them into one control. */
     spacing?: number
   }) {
   return (

package/src/components/ui/transfer-list.tsx

@@ -27,16 +27,22 @@ type TransferListItemBase = { value: string; label: string; disabled?: boolean }
 type TransferListValueChangeDetails<T> = {
   /** Values now on the target side, in catalog order. */
   value: string[]
+  /** Every item, in catalog order. */
   items: T[]
   /** What just moved and where. */
   moved: T[]
+  /** `right` moves source to target; `left` moves target to source. */
   direction: TransferListDirection
 }
 
 type TransferListContextValue<T = TransferListItemBase> = {
+  /** Every item, in catalog order. */
   items: T[]
+  /** Unique value for an item. */
   itemToValue: (item: T) => string
+  /** Label for an item. */
   itemToString: (item: T) => string
+  /** Returns true for items that can never move. */
   itemDisabled: (item: T) => boolean
   value: string[]
   /** Items on each side, in catalog order. */
@@ -78,9 +84,13 @@ const sideOf = (direction: TransferListDirection): TransferListSide => (directio
 /* ---------------------------------- root --------------------------------- */
 
 type TransferListProps<T> = Omit<React.ComponentProps<"div">, "defaultValue" | "onChange"> & {
+  /** Every item, in catalog order. */
   items: T[]
+  /** Unique value for an item. */
   itemToValue?: (item: T) => string
+  /** Label for an item. */
   itemToString?: (item: T) => string
+  /** Returns true for items that can never move. */
   itemDisabled?: (item: T) => boolean
   /** Values on the target side. Kept in catalog order. */
   value?: string[]
@@ -205,6 +215,7 @@ function TransferList<T = TransferListItemBase>({
       )
       onValueChange?.({
         value: next,
+        /** Every item, in catalog order. */
         items: items.filter((i) => next.includes(itemToValue(i))),
         moved: movedItems,
         direction,

package/src/components/ui/tree-select.tsx

@@ -63,6 +63,7 @@ type TreeSelectContextValue<T extends TreeNode = TreeNode> = {
   multiple: boolean
   selectableBranches: boolean
   closeOnSelect: boolean
+  /** Controlled open branches. */
   expandedValue: string[]
   setExpandedValue: (value: string[]) => void
   open: boolean
@@ -107,8 +108,11 @@ type TreeSelectProps<T extends TreeNode> = Omit<
   selectableBranches?: boolean
   /** Close after a pick. Defaults to `!multiple`. */
   closeOnSelect?: boolean
+  /** Controlled open branches. */
   expandedValue?: string[]
+  /** Branches open initially when uncontrolled. */
   defaultExpandedValue?: string[]
+  /** Called when branches open or close. */
   onExpandedChange?: (details: { expandedValue: string[] }) => void
   open?: boolean
   defaultOpen?: boolean
@@ -328,6 +332,7 @@ function TreeSelectValue<T extends TreeNode>({
   ...props
 }: Omit<React.ComponentProps<"span">, "children"> & {
   placeholder?: React.ReactNode
+  /** Rendered between the selected labels. */
   separator?: string
   children?: (nodes: T[]) => React.ReactNode
 }) {

package/src/components/ui/virtual-list.tsx

@@ -19,6 +19,7 @@ type VirtualItem = {
 type ScrollAlign = "auto" | "start" | "center" | "end"
 
 type VirtualListContextValue = {
+  /** Total number of rows. */
   count: number
   items: VirtualItem[]
   totalSize: number
@@ -28,6 +29,7 @@ type VirtualListContextValue = {
   scrollToIndex: (index: number, options?: { align?: ScrollAlign; behavior?: ScrollBehavior }) => void
   scrollToOffset: (offset: number, behavior?: ScrollBehavior) => void
   viewportRef: React.RefObject<HTMLDivElement | null>
+  /** Stable React key for a row index. */
   getItemKey: (index: number) => React.Key
 }
 
@@ -56,14 +58,19 @@ function findIndex(starts: Float64Array, count: number, offset: number) {
 /* ---------------------------------- root --------------------------------- */
 
 type VirtualListProps = Omit<React.ComponentProps<"div">, "children"> & {
+  /** Total number of rows. */
   count: number
   /** Row height before measurement (a number, or per index). */
   estimateSize?: number | ((index: number) => number)
   /** Rows rendered beyond the visible window on each side. */
   overscan?: number
+  /** Space between rows in px. */
   gap?: number
+  /** Space before the first row in px. */
   paddingStart?: number
+  /** Space after the last row in px. */
   paddingEnd?: number
+  /** Stable React key for a row index. */
   getItemKey?: (index: number) => React.Key
   /** Fires when the rendered window changes. */
   onRangeChange?: (range: { start: number; end: number } | null) => void