@indielayer/ui 2.0.0 → 2.1.0

package/src/components/tooltip/ToggleTip.vue

@@ -1,12 +1,21 @@
 <script lang="ts">
 const toggleTipProps = {
-  content: String,
-  icon: String,
+  content: {
+    type: String,
+    description: 'HTML or text shown inside the tooltip.',
+  },
+  icon: {
+    type: String,
+    description: 'Icon name for the trigger. Defaults to the info icon.',
+  },
 }
 
 export type ToggleTipProps = ExtractPublicPropTypes<typeof toggleTipProps>
 
-export default { name: 'XToggleTip' }
+export default {
+  name: 'XToggleTip',
+  docs: {},
+}
 </script>
 
 <script setup lang="ts">

package/src/components/tooltip/Tooltip.vue

@@ -3,12 +3,20 @@ const tooltipProps = {
   tag: {
     type: String,
     default: 'div',
+    description: 'Root element tag wrapping the trigger.',
+  },
+  tooltip: {
+    type: String,
+    description: 'Tooltip text shown on hover. Prefer the tooltip slot for custom content.',
+  },
+  disabled: {
+    type: Boolean,
+    description: 'Disables showing the tooltip.',
   },
-  tooltip: String,
-  disabled: Boolean,
   position: {
     type: String as PropType<TooltipPosition>,
     default: 'bottom',
+    description: 'Preferred placement relative to the trigger (top, bottom, left, right).',
   },
 }
 
@@ -19,7 +27,15 @@ export type TooltipProps = ExtractPublicPropTypes<typeof tooltipProps>
 type InternalClasses = 'tooltip'
 export interface TooltipTheme extends ThemeComponent<TooltipProps, InternalClasses> {}
 
-export default { name: 'XTooltip' }
+export default {
+  name: 'XTooltip',
+  docs: {
+    slots: {
+      default: 'Trigger content the tooltip is attached to.',
+      tooltip: 'Custom tooltip content; overrides the `tooltip` prop.',
+    },
+  },
+}
 </script>
 
 <script setup lang="ts">

package/src/components/upload/Upload.vue

@@ -8,28 +8,46 @@ const validators = {
 const uploadProps = {
   ...useInteractive.props(),
   ...useInputtable.props(),
-  placeholder: String,
-  accept: String,
-  multiple: optionalBooleanProp(),
-  maxFiles: [Number, String],
-  maxFileSize: [Number, String],
+  placeholder: {
+    type: String,
+    description: 'Text shown in the default drop zone.',
+  },
+  accept: {
+    type: String,
+    description: 'Accepted file types (native `accept` attribute).',
+  },
+  multiple: optionalBooleanProp('Allows selecting more than one file.'),
+  maxFiles: {
+    type: [Number, String],
+    description: 'Maximum number of files allowed.',
+  },
+  maxFileSize: {
+    type: [Number, String],
+    description: 'Maximum file size in bytes.',
+  },
   variant: {
     type: String as PropType<UploadVariant>,
     default: 'box',
+    description: 'Visual variant of the upload control.',
+  },
+  action: {
+    type: String,
+    description: 'URL to upload files to; enables remote upload mode when set.',
+  },
+  headers: {
+    type: Object as PropType<Record<string, string>>,
+    description: 'Additional HTTP headers sent with the upload request.',
   },
-
-  // URL to submit data to.
-  action: String,
-  // Additional HTTP headers
-  headers: Object as PropType<Record<string, string>>,
   method: {
     type: String as PropType<'POST' | 'PUT'>,
     default: 'POST',
+    description: 'HTTP method used when uploading to `action`.',
   },
-  withCredentials: optionalBooleanProp(),
+  withCredentials: optionalBooleanProp('Sends cookies/credentials with the upload request.'),
   fileFormDataName: {
     type: String,
     default: 'file',
+    description: 'FormData field name for each uploaded file.',
   },
 }
 
@@ -50,6 +68,21 @@ export interface UploadTheme extends ThemeComponent<UploadProps, InternalClasses
 export default {
   name: 'XUpload',
   validators,
+  docs: {
+    slots: {
+      box: 'Custom drop zone UI (`is-over` when dragging files).',
+      files: 'Custom file list (`files` upload state array).',
+      removeIcon: 'Icon for the remove-file control.',
+    },
+    emits: {
+      ...useInputtable.emitDocs(),
+      upload: 'Emitted when a file finishes uploading (remote mode).',
+      remove: 'Emitted when a file is removed from the list.',
+    },
+    methods: {
+      ...useInputtable.methodDocs(),
+    },
+  },
 }
 </script>
 
@@ -61,6 +94,7 @@ import { useInteractive } from '../../composables/useInteractive'
 import { useInputtable } from '../../composables/useInputtable'
 import { useTheme, type ThemeComponent } from '../../composables/useTheme'
 import { uploadIcon, closeIcon, fileIcon } from '../../common/icons'
+import { isFileAccepted } from './fileAccept'
 
 import XLabel from '../label/Label.vue'
 import XInputFooter from '../inputFooter/InputFooter.vue'
@@ -104,12 +138,8 @@ function isInputValid(files: File[] | FileList | null) {
   }
 
   if (props.accept) {
-    const accept = props.accept.split(',').map((type) => type.trim())
-
     for (let i = 0; i < files.length; i++) {
-      const file = files[i]
-
-      if (!accept.some((type) => file.type === type || file.name.endsWith(type))) {
+      if (!isFileAccepted(files[i], props.accept)) {
         errorInternal.value = 'Invalid file type'
 
         return false

package/src/components/upload/__tests__/fileAccept.spec.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect } from 'vitest'
+import { isFileAccepted } from '../fileAccept'
+
+function file(name: string, type: string) {
+  return new File([''], name, { type })
+}
+
+describe('isFileAccepted', () => {
+  it('accepts any file when accept is empty', () => {
+    expect(isFileAccepted(file('a.png', 'image/png'), '')).toBe(true)
+    expect(isFileAccepted(file('a.png', 'image/png'), '   ')).toBe(true)
+  })
+
+  it('matches filename extensions (case-insensitive)', () => {
+    expect(isFileAccepted(file('photo.PNG', 'image/png'), '.png')).toBe(true)
+    expect(isFileAccepted(file('photo.jpg', 'image/jpeg'), '.png, .jpg')).toBe(true)
+    expect(isFileAccepted(file('doc.pdf', 'application/pdf'), '.png')).toBe(false)
+  })
+
+  it('matches exact MIME types', () => {
+    expect(isFileAccepted(file('a.png', 'image/png'), 'image/png')).toBe(true)
+    expect(isFileAccepted(file('a.png', 'image/png'), 'image/jpeg')).toBe(false)
+  })
+
+  it('matches MIME wildcards like image/*', () => {
+    expect(isFileAccepted(file('a.png', 'image/png'), 'image/*')).toBe(true)
+    expect(isFileAccepted(file('a.webp', 'image/webp'), 'image/*')).toBe(true)
+    expect(isFileAccepted(file('a.pdf', 'application/pdf'), 'image/*')).toBe(false)
+  })
+
+  it('matches mixed HTML accept lists', () => {
+    const accept = 'image/*,.pdf,application/json'
+
+    expect(isFileAccepted(file('a.png', 'image/png'), accept)).toBe(true)
+    expect(isFileAccepted(file('a.PDF', 'application/pdf'), accept)).toBe(true)
+    expect(isFileAccepted(file('a.json', 'application/json'), accept)).toBe(true)
+    expect(isFileAccepted(file('a.txt', 'text/plain'), accept)).toBe(false)
+  })
+})

package/src/components/upload/fileAccept.ts

@@ -0,0 +1,29 @@
+/**
+ * Matches a file against an HTML `accept` attribute value.
+ * Supports extensions (`.png`), MIME types (`image/png`), and wildcards (`image/*`).
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Attributes/accept
+ */
+export function isFileAccepted(file: File, accept: string): boolean {
+  const tokens = accept.split(',').map((token) => token.trim()).filter(Boolean)
+
+  if (!tokens.length) return true
+
+  const fileName = file.name.toLowerCase()
+  const fileType = file.type.toLowerCase()
+
+  return tokens.some((token) => {
+    const type = token.toLowerCase()
+
+    if (type.startsWith('.')) {
+      return fileName.endsWith(type)
+    }
+
+    if (type.endsWith('/*')) {
+      const category = type.slice(0, -2)
+
+      return fileType.startsWith(`${category}/`)
+    }
+
+    return fileType === type
+  })
+}

package/src/composables/useColors.ts

@@ -94,5 +94,6 @@ useColors.props = (defaultColor?: string) => ({
   color: {
     type: String,
     default: defaultColor,
+    description: 'Theme or CSS color used for the control accents.',
   },
 } as const)

package/src/composables/useCommon.ts

@@ -13,6 +13,7 @@ useCommon.props = () => ({
     type: String as PropType<Size>,
     default: 'md',
     validator: (value: string) => validators.size.includes(value),
+    description: 'Control size. One of xs, sm, md, lg, xl.',
   },
 } as const)
 

package/src/composables/useFocusTrap.ts

@@ -97,7 +97,9 @@ export function useFocusTrap() {
   }
 
   function clearFocusTrap(options?: { returnFocus?: boolean; }) {
-    document.removeEventListener('keydown', handleKeydown)
+    if (typeof document !== 'undefined') {
+      document.removeEventListener('keydown', handleKeydown)
+    }
     observer?.disconnect()
     observer = null
     if (options?.returnFocus && prevActiveElement) {

package/src/composables/useInputtable.ts

@@ -201,27 +201,83 @@ useInputtable.emits = (withListeners = true): string[] => {
     ['update:modelValue']
 }
 
+useInputtable.emitDocs = (withListeners = true): Record<string, string> => {
+  const docs: Record<string, string> = {
+    'update:modelValue': 'Emitted when the bound value changes (v-model).',
+  }
+
+  if (withListeners) {
+    docs.blur = 'Emitted when the field loses focus.'
+    docs.focus = 'Emitted when the field receives focus.'
+    docs.input = 'Emitted on native input events.'
+    docs.change = 'Emitted when the value is committed (change).'
+  }
+
+  return docs
+}
+
+useInputtable.methodDocs = (): Record<string, string> => ({
+  focus: 'Focus the underlying control.',
+  blur: 'Remove focus from the underlying control.',
+  reset: 'Reset the field value and validation state.',
+  validate: 'Run validation rules and return whether the field is valid.',
+  setError: 'Set an external error message on the field.',
+})
+
 useInputtable.props = () => ({
   modelValue: {
     type: [String, Number, Boolean, Object, Array] as PropType<string | number | boolean | object | any[] | undefined>,
     default: undefined,
+    description: 'Bound value (v-model).',
+  },
+  id: {
+    type: String,
+    description: 'Native id attribute for the input element.',
+  },
+  name: {
+    type: String,
+    description: 'Native name attribute for form submission.',
+  },
+  readonly: {
+    type: Boolean,
+    description: 'Makes the field read-only without disabling it.',
+  },
+  required: {
+    type: Boolean,
+    description: 'Marks the field as required for validation.',
   },
-  id: String,
-  name: String,
-  readonly: Boolean,
-  required: Boolean,
   validateOnInput: {
     type: Boolean,
     default: true,
+    description: 'Runs validation on each input event when true.',
+  },
+  label: {
+    type: String,
+    description: 'Visible label text for the field.',
+  },
+  helper: {
+    type: String,
+    description: 'Helper text shown below the field.',
+  },
+  error: {
+    type: String,
+    description: 'External error message; overrides rule errors when set.',
+  },
+  hideFooter: {
+    type: Boolean,
+    description: 'Hides the footer area (helper / error).',
   },
-  label: String,
-  helper: String,
-  error: String,
-  hideFooter: Boolean,
   rules: {
     type: Array,
     default: () => [],
+    description: 'Validation rule functions or rule descriptors.',
+  },
+  tooltip: {
+    type: String,
+    description: 'Optional tooltip text next to the label.',
+  },
+  skipFormRegistry: {
+    type: Boolean,
+    description: 'Skips registering this field with a parent x-form.',
   },
-  tooltip: String,
-  skipFormRegistry: Boolean,
 } as const)

package/src/composables/useInteractive.ts

@@ -18,11 +18,21 @@ export const useInteractive = (
 }
 
 useInteractive.props = () => ({
-  disabled: Boolean,
-  loading: Boolean,
-  loadingLabel: String,
+  disabled: {
+    type: Boolean,
+    description: 'Disables interaction and applies disabled styling.',
+  },
+  loading: {
+    type: Boolean,
+    description: 'Shows a loading indicator and blocks interaction.',
+  },
+  loadingLabel: {
+    type: String,
+    description: 'Accessible label announced while loading.',
+  },
   loadingStatus: {
     type: String as PropType<LoaderStatus>,
     default: 'active',
+    description: 'Loader visual status (for example active or indeterminate).',
   },
 } as const)

package/src/themes/base/styles.ts

@@ -3,6 +3,7 @@ export default `
   html {
     color: #111827;
     background-color: white;
+    color-scheme: light;
   }
 
   html.dark {
@@ -27,9 +28,7 @@ export default `
   }
 
   .dark {
-    input[type="time"]::-webkit-calendar-picker-indicator{
-      filter: invert(100%);
-    }
+    color-scheme: dark;
   }
 }
 

package/src/themes/carbon/styles.ts

@@ -3,6 +3,7 @@ export default `
   html {
     color: #111827;
     background-color: white;
+    color-scheme: light;
   }
 
   html.dark {
@@ -23,9 +24,7 @@ export default `
   }
 
   .dark {
-    input[type="time"]::-webkit-calendar-picker-indicator{
-      filter: invert(100%);
-    }
+    color-scheme: dark;
   }
 }
 

package/src/version.ts

@@ -1 +1 @@
-export default '2.0.0'
+export default '2.1.0'

package/src/virtual/components/infiniteLoader/InfiniteLoader.vue

@@ -1,14 +1,46 @@
 <script lang="ts">
+const infiniteLoaderProps = {
+  isRowLoaded: {
+    type: Function as PropType<(index: number) => boolean>,
+    required: true,
+    description: 'Returns whether the row at the given index is already loaded.',
+  },
+  loadMoreRows: {
+    type: Function as PropType<(startIndex: number, stopIndex: number) => Promise<void>>,
+    required: true,
+    description: 'Loads more rows for the given index range; resolve when finished.',
+  },
+  minimumBatchSize: {
+    type: Number,
+    description: 'Minimum rows to request per load (default 10). Batches HTTP fetches.',
+  },
+  threshold: {
+    type: Number,
+    description: 'Prefetch when the user scrolls within this many rows of unloaded data (default 15).',
+  },
+  rowCount: {
+    type: Number,
+    required: true,
+    description: 'Total row count; may be an upper bound if the true size is unknown.',
+  },
+}
+
 export default {
   name: 'XInfiniteLoader',
+  docs: {
+    slots: {
+      default: 'Render prop slot; receives `onRowsRendered` to wire into a virtual list.',
+    },
+  },
 }
 </script>
 
 <script setup lang="ts">
+import type { PropType } from 'vue'
 import { useInfiniteLoader } from '../../composables/infinite-loader/useInfiniteLoader'
 import type { InfiniteLoaderProps } from '../../composables/infinite-loader/types'
 
-const props = defineProps<InfiniteLoaderProps>()
+const props = defineProps(infiniteLoaderProps) as unknown as InfiniteLoaderProps
 
 const { onRowsRendered } = useInfiniteLoader(props)
 </script>

package/src/virtual/components/virtualGrid/VirtualGrid.vue

@@ -1,22 +1,116 @@
 <script lang="ts">
+const virtualGridProps = {
+  cellProps: {
+    type: Object as PropType<Record<string, unknown>>,
+    description: 'Extra props passed to the cell slot as `props`.',
+  },
+  class: {
+    type: String,
+    description: 'CSS class name on the root element.',
+  },
+  columnCount: {
+    type: Number,
+    required: true,
+    description: 'Total number of columns in the grid.',
+  },
+  columnWidth: {
+    type: [Number, String, Function] as PropType<
+    number | string | ((index: number, cellProps: Record<string, unknown>) => number)
+    >,
+    required: true,
+    description: 'Column width as px, percent string, or a function of index.',
+  },
+  defaultHeight: {
+    type: Number,
+    default: 0,
+    description: 'Initial grid height before measure; important for SSR.',
+  },
+  defaultWidth: {
+    type: Number,
+    default: 0,
+    description: 'Initial grid width before measure; important for SSR.',
+  },
+  dir: {
+    type: String as PropType<'ltr' | 'rtl' | 'auto'>,
+    description: 'Text directionality for cell layout (ltr, rtl, or auto).',
+  },
+  onCellsRendered: {
+    type: Function as PropType<(
+      visibleCells: {
+        columnStartIndex: number;
+        columnStopIndex: number;
+        rowStartIndex: number;
+        rowStopIndex: number;
+      },
+      allCells: {
+        columnStartIndex: number;
+        columnStopIndex: number;
+        rowStartIndex: number;
+        rowStopIndex: number;
+      }
+    ) => void>,
+    description: 'Called when the visible or overscan cell range changes.',
+  },
+  onResize: {
+    type: Function as PropType<(
+      size: { height: number; width: number; },
+      prevSize: { height: number; width: number; }
+    ) => void>,
+    description: 'Called when the grid root resizes.',
+  },
+  overscanCount: {
+    type: Number,
+    default: 3,
+    description: 'Extra rows/columns rendered outside the visible area.',
+  },
+  rowCount: {
+    type: Number,
+    required: true,
+    description: 'Total number of rows in the grid.',
+  },
+  rowHeight: {
+    type: [Number, String, Function] as PropType<
+    number | string | ((index: number, cellProps: Record<string, unknown>) => number)
+    >,
+    required: true,
+    description: 'Row height as px, percent string, or a function of index.',
+  },
+  style: {
+    type: Object as PropType<CSSProperties>,
+    description: 'Inline styles; the grid fills the size defined here.',
+  },
+  tag: {
+    type: String as PropType<TagNames>,
+    default: 'div',
+    description: 'Root element tag.',
+  },
+}
+
 export default {
   name: 'XVirtualGrid',
+  docs: {
+    slots: {
+      cell: 'Render a single cell. Receives columnIndex, rowIndex, style, ariaAttributes, and props.',
+      default: 'Optional content rendered after the virtualized cells.',
+    },
+    methods: {
+      scrollToCell: 'Scroll so the given cell (row and column) is visible.',
+      scrollToColumn: 'Scroll so the given column index is visible.',
+      scrollToRow: 'Scroll so the given row index is visible.',
+      element: 'Root HTML element when mounted, otherwise null.',
+    },
+  },
 }
 </script>
 
 <script setup lang="ts">
-import { computed, ref, watch, type CSSProperties } from 'vue'
+import { computed, ref, watch, type CSSProperties, type PropType } from 'vue'
 import { useIsRtl } from '../../core/useIsRtl'
 import { useVirtualizer } from '../../core/useVirtualizer'
-import type { Align } from '../../types'
+import type { Align, TagNames } from '../../types'
 import type { VirtualGridProps, VirtualGridImperativeAPI } from './types'
 
-const props = withDefaults(defineProps<VirtualGridProps>(), {
-  defaultHeight: 0,
-  defaultWidth: 0,
-  overscanCount: 3,
-  tag: 'div',
-})
+const props = defineProps(virtualGridProps) as unknown as VirtualGridProps
 
 const element = ref<HTMLDivElement | null>(null)
 
@@ -42,7 +136,7 @@ const {
   itemProps: cellProps.value,
   itemSize: props.columnWidth,
   onResize: props.onResize,
-  overscanCount: props.overscanCount,
+  overscanCount: props.overscanCount ?? 3,
 })
 
 const {
@@ -62,7 +156,7 @@ const {
   itemProps: cellProps.value,
   itemSize: props.rowHeight,
   onResize: props.onResize,
-  overscanCount: props.overscanCount,
+  overscanCount: props.overscanCount ?? 3,
 })
 
 // Expose imperative API