@rokkit/ui 1.0.4 → 1.1.0

package/src/types/carousel.ts

@@ -0,0 +1,49 @@
+/**
+ * Carousel Component Types
+ */
+
+import type { Snippet } from 'svelte'
+
+/** Transition effect between carousel slides. */
+export type CarouselTransition = 'slide' | 'fade' | 'none'
+
+/**
+ * Props for the Carousel component.
+ */
+export interface CarouselProps {
+	/** Number of slides (required when using the `children` snippet). */
+	count?: number
+
+	/** Current slide index (bindable). */
+	current?: number
+
+	/** Auto-advance slides. */
+	autoplay?: boolean
+
+	/** Autoplay interval in milliseconds. Default `5000`. */
+	interval?: number
+
+	/** Wrap around at the ends. Default `true`. */
+	loop?: boolean
+
+	/** Show navigation dots. Default `true`. */
+	showDots?: boolean
+
+	/** Show prev / next arrow buttons. Default `true`. */
+	showArrows?: boolean
+
+	/** Transition effect. Default `'slide'`. */
+	transition?: CarouselTransition
+
+	/** Accessible label overrides for built-in controls. */
+	labels?: Record<string, string>
+
+	/** Additional CSS class. */
+	class?: string
+
+	/** Slide content — receives `(index, current)`. */
+	slide?: Snippet<[number, number]>
+
+	/** Children snippet (alternative to `slide`). */
+	children?: Snippet
+}

package/src/types/code.ts

@@ -1,7 +1,8 @@
 /**
- * Code component types
+ * Code component types — Code, CodeBlock, CodeGroup
  */
 
+import type { Snippet } from 'svelte'
 import { DEFAULT_STATE_ICONS } from '@rokkit/core'
 
 /** Supported themes for code highlighting */
@@ -44,3 +45,103 @@ export interface CodeProps {
 	/** Additional CSS class */
 	class?: string
 }
+
+/**
+ * Shiki theme mode for CodeBlock.
+ *
+ * `'auto'` follows `body[data-mode]` (light / dark). Pass `'light'` or
+ * `'dark'` to force a theme.
+ */
+export type CodeBlockTheme = 'auto' | 'light' | 'dark'
+
+/**
+ * Props for the CodeBlock component.
+ *
+ * Wraps a Shiki-highlighted code body in a Frame whose header carries the
+ * filename + language chip and optional action buttons.
+ */
+export interface CodeBlockProps {
+	/** The code body. */
+	code: string
+
+	/** Language label shown as a chip in the header and used for highlighting. */
+	language?: string
+
+	/** Filename label shown in the header. */
+	filename?: string
+
+	/** Max height (CSS length) of the scrollable code area. No cap when unset. */
+	height?: string
+
+	/** Shiki theme mode. Default `'auto'`. */
+	theme?: CodeBlockTheme
+
+	/** Show the copy-to-clipboard button. Default `false`. */
+	allowCopy?: boolean
+
+	/** Show the download-as-file button. Default `false`. */
+	allowDownload?: boolean
+
+	/** Optional extra-actions slot rendered after copy / download. */
+	actions?: Snippet
+}
+
+/**
+ * One file in a CodeGroup.
+ *
+ * The `path` doubles as id and tree placement (e.g. `src/lib/Button.svelte`).
+ * Intermediate segments become folder nodes; the final segment becomes a
+ * file leaf.
+ */
+export interface CodeGroupFile {
+	/** Full path used as id and for tree placement. */
+	path: string
+
+	/** Shiki language id. */
+	language: string
+
+	/** Source code. */
+	code: string
+
+	/** Display name override — defaults to the path's last segment. */
+	name?: string
+
+	/** File icon override (full icon class) — defaults to extension lookup. */
+	icon?: string
+}
+
+/**
+ * Icon overrides for the CodeGroup component, grouped by semantic category.
+ */
+export interface CodeGroupIconOverrides {
+	doc?: Partial<typeof DEFAULT_STATE_ICONS.doc>
+	folder?: Partial<typeof DEFAULT_STATE_ICONS.folder>
+	view?: Partial<typeof DEFAULT_STATE_ICONS.view>
+	action?: Partial<typeof DEFAULT_STATE_ICONS.action>
+}
+
+/**
+ * Props for the CodeGroup component.
+ *
+ * Renders a hierarchical tree picker over multiple files with an optional
+ * collapsible preview panel.
+ */
+export interface CodeGroupProps {
+	/** Files rendered in the group. */
+	files: CodeGroupFile[]
+
+	/** Path of the file selected on first render. Defaults to the first file. */
+	initialFile?: string
+
+	/** Additional CSS class. */
+	class?: string
+
+	/** Icon overrides per semantic category. */
+	icons?: CodeGroupIconOverrides
+
+	/** Optional preview content — toggled by a "Show preview" action. */
+	preview?: Snippet
+
+	/** Show the copy button on the inner CodeBlock. Default `true`. */
+	showCopyButton?: boolean
+}

package/src/types/connector.ts

@@ -0,0 +1,22 @@
+/**
+ * Connector Component Types
+ *
+ * The `Connector` component renders tree-line connectors used by hierarchical
+ * visualizations (Tree, lists with indent guides). The underlying connector
+ * type values are defined in `./tree.ts` and re-exported here for ergonomics.
+ */
+
+import type { ConnectorType } from './tree.js'
+
+export type { ConnectorType } from './tree.js'
+
+/**
+ * Props for the Connector component.
+ */
+export interface ConnectorProps {
+	/** The type of connector to render. Default `'empty'`. */
+	type?: ConnectorType
+
+	/** Right-to-left layout support. */
+	rtl?: boolean
+}

package/src/types/divider.ts

@@ -0,0 +1,20 @@
+/**
+ * Divider Component Types
+ */
+
+/** Divider orientation. */
+export type DividerOrientation = 'horizontal' | 'vertical'
+
+/**
+ * Props for the Divider component.
+ */
+export interface DividerProps {
+	/** Orientation of the divider. */
+	orientation?: DividerOrientation
+
+	/** Optional label text rendered inline with the divider. */
+	label?: string
+
+	/** Additional CSS class. */
+	class?: string
+}

package/src/types/frame.ts

@@ -0,0 +1,29 @@
+/**
+ * Frame Component Types
+ *
+ * Generic header / body / footer container primitive — used by CodeBlock,
+ * PlotPlugin and other "card-shaped UI block" surfaces. For an interactive
+ * card (link / button) prefer `<Card/>`.
+ */
+
+import type { Snippet } from 'svelte'
+
+/**
+ * Props for the Frame component.
+ */
+export interface FrameProps {
+	/** Top slot — title, action chips, status badges, etc. */
+	header?: Snippet
+
+	/** Main content. */
+	children?: Snippet
+
+	/** Bottom slot — metadata, actions, secondary controls. */
+	footer?: Snippet
+
+	/**
+	 * When true the body slot has zero padding so the inner artifact
+	 * (a chart, a `<pre>`, a table) controls its own padding.
+	 */
+	flush?: boolean
+}

package/src/types/index.ts

@@ -56,3 +56,69 @@ export * from './upload-progress.js'
 
 // Tooltip Types
 export * from './tooltip.js'
+
+// ItemContent Types
+export * from './item-content.js'
+
+// StatusList Types
+export * from './status-list.js'
+
+// AlertList Types
+export * from './alert-list.js'
+
+// Avatar Types
+export * from './avatar.js'
+
+// Badge Types
+export * from './badge.js'
+
+// BreadCrumbs Types
+export * from './breadcrumbs.js'
+
+// Card Types
+export * from './card.js'
+
+// Carousel Types
+export * from './carousel.js'
+
+// Connector Types
+export * from './connector.js'
+
+// Divider Types
+export * from './divider.js'
+
+// Frame Types
+export * from './frame.js'
+
+// Message Types
+export * from './message.js'
+
+// NavContent Types
+export * from './nav-content.js'
+
+// Pill Types
+export * from './pill.js'
+
+// ProgressBar Types
+export * from './progress-bar.js'
+
+// Rating Types
+export * from './rating.js'
+
+// ResponsiveGrid Types
+export * from './responsive-grid.js'
+
+// Reveal Types
+export * from './reveal.js'
+
+// Shine Types
+export * from './shine.js'
+
+// Stack Types
+export * from './stack.js'
+
+// Stepper Types
+export * from './stepper.js'
+
+// Tilt Types
+export * from './tilt.js'

package/src/types/item-content.ts

@@ -0,0 +1,26 @@
+/**
+ * ItemContent Component Types
+ *
+ * Default inner content for List / Menu / Tree / Toolbar items.
+ * Renders avatar/icon, label + subtext, optional badge and shortcut from a
+ * ProxyItem wrapper that exposes field access and reactive state.
+ */
+
+import type { ProxyItem } from '@rokkit/states'
+
+/**
+ * Props for the ItemContent component.
+ */
+export interface ItemContentProps {
+	/**
+	 * ProxyItem wrapper around the underlying data — exposes `label`,
+	 * `get(field)`, and the item's reactive selection / expansion state.
+	 */
+	proxy: ProxyItem
+
+	/** Render the avatar / icon slot. Default: `true`. */
+	showIcon?: boolean
+
+	/** Render the description / subtext line under the label. Default: `true`. */
+	showSubtext?: boolean
+}

package/src/types/message.ts

@@ -0,0 +1,54 @@
+/**
+ * Message Component Types
+ */
+
+import type { Snippet } from 'svelte'
+
+/** Semantic message type — drives color treatment and the default icon. */
+export type MessageType = 'error' | 'info' | 'success' | 'warning'
+
+/**
+ * Icon overrides for the Message component, keyed by message type.
+ */
+export interface MessageIcons {
+	error?: string
+	info?: string
+	success?: string
+	warning?: string
+}
+
+/**
+ * Props for the Message component.
+ */
+export interface MessageProps {
+	/** Message type — controls color and the default icon. */
+	type?: MessageType
+
+	/** Icon class overrides per type. */
+	icons?: MessageIcons
+
+	/** Text content (shorthand). `children` takes precedence when both provided. */
+	text?: string
+
+	/** Show a dismiss button. */
+	dismissible?: boolean
+
+	/**
+	 * Auto-dismiss after N milliseconds. Defaults to `4000` when not
+	 * `dismissible`, otherwise persistent (no auto-dismiss). Pass `0`
+	 * to disable auto-dismissal explicitly.
+	 */
+	timeout?: number
+
+	/** Optional action buttons snippet. */
+	actions?: Snippet
+
+	/** Rich content (takes precedence over `text`). */
+	children?: Snippet
+
+	/** Called when dismissed — via button click or timeout. */
+	ondismiss?: () => void
+
+	/** Additional CSS class. */
+	class?: string
+}

package/src/types/nav-content.ts

@@ -0,0 +1,31 @@
+/**
+ * NavContent Component Types
+ */
+
+import type { Snippet } from 'svelte'
+
+/** Layout orientation. */
+export type NavContentOrientation = 'horizontal' | 'vertical'
+
+/**
+ * Props for the NavContent component.
+ */
+export interface NavContentProps {
+	/** Layout orientation. */
+	orientation?: NavContentOrientation
+
+	/** Nav panel width (horizontal) or height (vertical) — CSS length value. */
+	navSize?: string
+
+	/** Collapse the nav panel on small screens. */
+	collapsible?: boolean
+
+	/** Nav panel snippet. */
+	nav: Snippet
+
+	/** Content panel snippet. */
+	content: Snippet
+
+	/** Additional CSS class. */
+	class?: string
+}

package/src/types/pill.ts

@@ -0,0 +1,43 @@
+/**
+ * Pill Component Types
+ */
+
+import type { Snippet } from 'svelte'
+import type { ProxyItem } from '@rokkit/states'
+
+/**
+ * Icon overrides for the Pill component.
+ */
+export interface PillIcons {
+	/** Icon class for the remove button. */
+	remove?: string
+}
+
+/**
+ * Props for the Pill component.
+ */
+export interface PillProps {
+	/** Item data — primitive (string / number) or an object. */
+	value: unknown
+
+	/** Custom field mappings used by the internal `ProxyItem`. */
+	fields?: Record<string, string>
+
+	/** Show the remove button (and enable Delete / Backspace shortcuts). */
+	removable?: boolean
+
+	/** Disabled state. */
+	disabled?: boolean
+
+	/** Custom icon overrides. */
+	icons?: PillIcons
+
+	/** Called when remove is triggered — via click or Delete / Backspace. */
+	onremove?: (value: unknown) => void
+
+	/** Custom content snippet — receives the pill's `ProxyItem`. */
+	content?: Snippet<[ProxyItem]>
+
+	/** Additional CSS class. */
+	class?: string
+}

package/src/types/progress-bar.ts

@@ -0,0 +1,19 @@
+/**
+ * ProgressBar Component Types
+ */
+
+/**
+ * Props for the ProgressBar component.
+ *
+ * Pass `value = null` (or omit it) to render in indeterminate state.
+ */
+export interface ProgressBarProps {
+	/** Current progress value. `null` (or undefined) renders indeterminate. */
+	value?: number | null
+
+	/** Maximum value. Default `100`. */
+	max?: number
+
+	/** Additional CSS class. */
+	class?: string
+}

package/src/types/rating.ts

@@ -0,0 +1,43 @@
+/**
+ * Rating Component Types
+ */
+
+/**
+ * Icon overrides for the Rating component.
+ */
+export interface RatingIcons {
+	/** Icon class for a filled star. */
+	filled?: string
+
+	/** Icon class for an empty star. */
+	empty?: string
+
+	/** Icon class for a half-filled star. */
+	half?: string
+}
+
+/**
+ * Props for the Rating component.
+ */
+export interface RatingProps {
+	/** Current rating value (bindable). */
+	value?: number
+
+	/** Maximum number of stars. Default `5`. */
+	max?: number
+
+	/** Disabled state. */
+	disabled?: boolean
+
+	/** Accessible label for the surrounding radio group. */
+	label?: string
+
+	/** Custom icon overrides. */
+	icons?: RatingIcons
+
+	/** Called when the value changes. */
+	onchange?: (value: number) => void
+
+	/** Additional CSS class. */
+	class?: string
+}

package/src/types/responsive-grid.ts

@@ -0,0 +1,25 @@
+/**
+ * ResponsiveGrid Component Types
+ */
+
+import type { Snippet } from 'svelte'
+
+/**
+ * Props for the ResponsiveGrid component.
+ */
+export interface ResponsiveGridProps {
+	/** Minimum column width — CSS length value. */
+	minWidth?: string
+
+	/** Gap between cells — CSS length value. */
+	gap?: string
+
+	/** Maximum number of columns. */
+	maxCols?: number
+
+	/** Grid children. */
+	children: Snippet
+
+	/** Additional CSS class. */
+	class?: string
+}

package/src/types/reveal.ts

@@ -0,0 +1,49 @@
+/**
+ * Reveal Component Types
+ */
+
+import type { Snippet } from 'svelte'
+
+/** Slide direction for the reveal animation. */
+export type RevealDirection = 'up' | 'down' | 'left' | 'right' | 'none'
+
+/**
+ * Props for the Reveal component.
+ *
+ * Wraps the `reveal` action so children animate in once they intersect the
+ * viewport.
+ */
+export interface RevealProps {
+	/** Slide direction. Default `'up'`. */
+	direction?: RevealDirection
+
+	/** Slide distance — CSS length value. Default `'1.5rem'`. */
+	distance?: string
+
+	/** Transition duration in milliseconds. Default `600`. */
+	duration?: number
+
+	/** Delay before animation starts in milliseconds. Default `0`. */
+	delay?: number
+
+	/**
+	 * Delay increment per direct child in milliseconds — used for staggered
+	 * reveals. Default `0`.
+	 */
+	stagger?: number
+
+	/** Animate only on first intersection. Default `true`. */
+	once?: boolean
+
+	/** IntersectionObserver threshold (0–1). Default `0.1`. */
+	threshold?: number
+
+	/** CSS easing function. */
+	easing?: string
+
+	/** Additional CSS class. */
+	class?: string
+
+	/** Content to reveal. */
+	children?: Snippet
+}

package/src/types/shine.ts

@@ -0,0 +1,37 @@
+/**
+ * Shine Component Types
+ *
+ * Renders an SVG specular-lighting filter that tracks pointer position to
+ * give wrapped content a moving highlight.
+ */
+
+import type { Snippet } from 'svelte'
+
+/**
+ * Props for the Shine component.
+ */
+export interface ShineProps {
+	/** Light color. Default `'rgb(var(--primary-500))'`. */
+	color?: string
+
+	/** Light source distance / height — controls highlight spread. Default `300`. */
+	radius?: number
+
+	/** Gaussian blur depth applied to the highlight. Default `1`. */
+	depth?: number
+
+	/** Surface height for the light filter. Default `2`. */
+	surfaceScale?: number
+
+	/** Reflection size — bigger = bigger reflection. Default `0.75`. */
+	specularConstant?: number
+
+	/** Light source focus — bigger = brighter. Default `120`. */
+	specularExponent?: number
+
+	/** Additional CSS class. */
+	class?: string
+
+	/** Content the highlight wraps. */
+	children?: Snippet
+}

package/src/types/stack.ts

@@ -0,0 +1,40 @@
+/**
+ * Stack Component Types
+ */
+
+import type { Snippet } from 'svelte'
+
+/** Layout direction. */
+export type StackDirection = 'vertical' | 'horizontal'
+
+/** Gap size between children — maps to the theme's spacing scale. */
+export type StackGap = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+
+/** Cross-axis alignment. */
+export type StackAlign = 'start' | 'center' | 'end' | 'stretch'
+
+/** Main-axis justification. */
+export type StackJustify = 'start' | 'center' | 'end' | 'between' | 'around'
+
+/**
+ * Props for the Stack component.
+ */
+export interface StackProps {
+	/** Layout direction. */
+	direction?: StackDirection
+
+	/** Gap size between children. */
+	gap?: StackGap
+
+	/** Cross-axis alignment. */
+	align?: StackAlign
+
+	/** Main-axis justification. */
+	justify?: StackJustify
+
+	/** Stack children. */
+	children: Snippet
+
+	/** Additional CSS class. */
+	class?: string
+}