@rokkit/ui 1.0.5 → 1.1.0

package/src/types/status-list.ts

@@ -0,0 +1,42 @@
+/**
+ * StatusList Component Types
+ *
+ * Renders a vertical list of status rows — each with a label and a status
+ * keyword that maps to a badge icon (e.g. `pass`, `fail`, `warn`).
+ */
+
+import { DEFAULT_STATE_ICONS } from '@rokkit/core'
+
+/**
+ * Built-in badge status keys provided by `@rokkit/core`. Consumers may also
+ * pass any other string and supply a matching entry via the `icons` prop.
+ */
+export type StatusListStatus = keyof typeof DEFAULT_STATE_ICONS.badge | (string & {})
+
+/**
+ * One row in a StatusList — a label paired with a status keyword.
+ */
+export interface StatusListItem {
+	/** Text rendered for this row. */
+	text: string
+
+	/** Status keyword used to look up the badge icon. */
+	status: StatusListStatus
+}
+
+/**
+ * Props for the StatusList component.
+ */
+export interface StatusListProps {
+	/** Additional CSS class applied to the root element. */
+	class?: string
+
+	/** Rows to render. */
+	items: StatusListItem[]
+
+	/**
+	 * Override the default badge icon map (`pass` / `fail` / `warn` / `unknown`).
+	 * Merged on top of `DEFAULT_STATE_ICONS.badge` from `@rokkit/core`.
+	 */
+	icons?: Partial<Record<string, string>>
+}

package/src/types/stepper.ts

@@ -0,0 +1,74 @@
+/**
+ * Stepper Component Types
+ */
+
+import type { Snippet } from 'svelte'
+
+/** Layout orientation for the stepper. */
+export type StepperOrientation = 'horizontal' | 'vertical'
+
+/**
+ * Definition for a single step in the stepper.
+ */
+export interface StepperStep {
+	/** Step label (shown below the circle). */
+	text: string
+
+	/** Short text shown inside the circle. Default: step number. */
+	label?: string
+
+	/** Step is finished — shows the check icon. */
+	completed?: boolean
+
+	/** Step cannot be navigated to. */
+	disabled?: boolean
+
+	/** Number of sub-stages within this step. Default `1`. */
+	stages?: number
+}
+
+/**
+ * Icon overrides for the Stepper component.
+ */
+export interface StepperIcons {
+	/** Icon class for the check / completed state. */
+	check?: string
+}
+
+/**
+ * Props for the Stepper component.
+ */
+export interface StepperProps {
+	/** Array of step definitions. */
+	steps?: StepperStep[]
+
+	/** Current step index (bindable). */
+	current?: number
+
+	/** Current sub-stage within the step (bindable, 0-based). */
+	currentStage?: number
+
+	/**
+	 * In linear mode only completed steps + the first incomplete step
+	 * are clickable.
+	 */
+	linear?: boolean
+
+	/** Layout orientation. */
+	orientation?: StepperOrientation
+
+	/** Accessible label for the surrounding group. */
+	label?: string
+
+	/** Custom icon overrides. */
+	icons?: StepperIcons
+
+	/** Called when a step (or sub-stage dot) is clicked. */
+	onclick?: (step: number, stage?: number) => void
+
+	/** Content snippet rendered below the stepper. */
+	content?: Snippet<[StepperStep, number]>
+
+	/** Additional CSS class. */
+	class?: string
+}

package/src/types/tilt.ts

@@ -0,0 +1,28 @@
+/**
+ * Tilt Component Types
+ */
+
+import type { Snippet } from 'svelte'
+
+/**
+ * Props for the Tilt component.
+ *
+ * Wraps content in a container that rotates in response to pointer
+ * movement, with optional brightness modulation.
+ */
+export interface TiltProps {
+	/** Maximum rotation angle in degrees. Default `10`. */
+	maxRotation?: number
+
+	/** Whether to adjust brightness based on pointer Y position. */
+	setBrightness?: boolean
+
+	/** CSS perspective value in pixels. Default `600`. */
+	perspective?: number
+
+	/** Additional CSS class. */
+	class?: string
+
+	/** Content to tilt. */
+	children?: Snippet
+}

package/src/types/toggle.ts

@@ -32,10 +32,22 @@ export type ToggleItemSnippet = Snippet<[ProxyItem, boolean]>
 // Component Props Types
 // =============================================================================
 
+/**
+ * Visual variant of the Toggle.
+ * - `'group'` (default) — segmented radio-group rendering, one button per option.
+ * - `'button'` — single button that cycles through the options on each click.
+ *   The rendered content represents the *next* option (the one you'd switch to),
+ *   so users can read the click destination at a glance.
+ */
+export type ToggleVariant = 'group' | 'button'
+
 /**
  * Props for the Toggle component
  */
 export interface ToggleProps {
+	/** Visual variant. Default: 'group'. */
+	variant?: ToggleVariant
+
 	/** Array of toggle options (strings, numbers, or objects) */
 	options?: ToggleItem[]
 

package/src/types/tree.ts

@@ -14,17 +14,59 @@ import { DEFAULT_STATE_ICONS } from '@rokkit/core'
 // =============================================================================
 
 /**
- * Field mapping configuration for tree data.
- * Extends base field mapping with tree-specific fields.
+ * Field mapping configuration for tree data — what the consumer passes
+ * to the Tree component. Both `expanded` and `level` are optional here
+ * because Tree falls back to `defaultTreeFields` for any field the
+ * consumer omits.
+ *
+ * Inside Tree the fields are merged with `defaultTreeFields` to produce
+ * a `ResolvedTreeFields` value where every key is guaranteed present.
+ * Downstream code that needs string field names without null-guards
+ * should use `ResolvedTreeFields` rather than `TreeFields`.
  */
 export interface TreeFields extends Record<string, string> {
-	/** Field for expanded state - default: 'expanded' */
+	/**
+	 * Name of the field on each tree item that holds its expanded state.
+	 * The value at that field is expected to be a `boolean`.
+	 *
+	 * Optional — falls back to the default field name `'expanded'`. After
+	 * `resolveTreeFields` is applied the resolved key is guaranteed present
+	 * (see {@link ResolvedTreeFields}).
+	 */
 	expanded?: string
 
-	/** Field for node level/depth - default: 'level' */
+	/**
+	 * Name of the field on each tree item that holds its depth in the tree.
+	 * The value at that field is expected to be a `number`.
+	 *
+	 * Optional — falls back to the default field name `'level'`. After
+	 * `resolveTreeFields` is applied the resolved key is guaranteed present
+	 * (see {@link ResolvedTreeFields}).
+	 */
 	level?: string
 }
 
+/**
+ * Tree fields after defaults have been applied — every field name is a
+ * non-null string. Use this type for any function or store that needs
+ * to read a field name without re-applying defaults.
+ *
+ * Construct from a `TreeFields` via `resolveTreeFields(fields)` (or by
+ * spreading `defaultTreeFields` first, e.g.
+ * `{ ...defaultTreeFields, ...userFields }`).
+ */
+export type ResolvedTreeFields = Required<TreeFields>
+
+/**
+ * Merge consumer-provided field overrides with the default field
+ * mapping so every key resolves to a string. Tree calls this once on
+ * its `fields` prop before passing the result to ProxyTree / line
+ * builders.
+ */
+export function resolveTreeFields(fields: TreeFields = {}): ResolvedTreeFields {
+	return { ...defaultTreeFields, ...fields }
+}
+
 /**
  * Default field mapping values for tree
  */

package/src/utils/palette.ts

@@ -719,16 +719,18 @@ export function resetPalette(
 }
 
 /**
- * Save palette to localStorage
+ * Save palette to localStorage. SSR-safe.
  */
 export function savePalette(key: string, mapping: Partial<Record<ColorRole, string>>): void {
+	if (typeof localStorage === 'undefined') return
 	localStorage.setItem(key, JSON.stringify(mapping))
 }
 
 /**
- * Load palette from localStorage
+ * Load palette from localStorage. SSR-safe.
  */
 export function loadPalette(key: string): Partial<Record<ColorRole, string>> | null {
+	if (typeof localStorage === 'undefined') return null
 	const stored = localStorage.getItem(key)
 	if (stored) {
 		try {

package/src/utils/shiki.ts

@@ -76,6 +76,27 @@ function resolveTheme(themeOption: string | undefined): BundledTheme {
 	return themeOption as BundledTheme
 }
 
+/**
+ * Map fence languages (used by @rokkit/blocks plugins) to a Shiki-known
+ * grammar. The fence is *semantic* (the renderer routes by language name),
+ * but the body is plain JSON — highlight it as such instead of falling
+ * back to unstyled text.
+ */
+const LANGUAGE_ALIASES: Record<string, BundledLanguage> = {
+	plot: 'json',
+	table: 'json',
+	form: 'json',
+	list: 'json',
+	stepper: 'json',
+	sparkline: 'json',
+	chart: 'json'
+}
+
+function resolveLang(input: string | undefined): BundledLanguage {
+	if (!input) return 'text' as BundledLanguage
+	return (LANGUAGE_ALIASES[input] ?? input) as BundledLanguage
+}
+
 function isValidCode(code: unknown): code is string {
 	return Boolean(code) && typeof code === 'string'
 }
@@ -84,7 +105,7 @@ export async function highlightCode(code: string, options: HighlightOptions = {}
 	if (!isValidCode(code)) throw new Error('Invalid code provided for highlighting')
 
 	const hl = await initializeHighlighter()
-	const lang = (options.lang ?? 'text') as BundledLanguage
+	const lang = resolveLang(options.lang as string | undefined)
 	const theme = resolveTheme(options.theme)
 	const loadedLangs = hl.getLoadedLanguages()
 	const effectiveLang = loadedLangs.includes(lang) ? lang : 'text'

package/src/utils/upload.js

@@ -61,11 +61,11 @@ export function validateFile(file, { accept, maxSize } = {}) {
  * @returns {string}
  */
 const MIME_PREFIX_ICONS = [
-	['image/', 'i-lucide:image'],
-	['video/', 'i-lucide:video'],
-	['audio/', 'i-lucide:music'],
-	['text/', 'i-lucide:file-text'],
-	['application/pdf', 'i-lucide:file-text']
+	['image/', 'media-image'],
+	['video/', 'media-video'],
+	['audio/', 'media-audio'],
+	['text/', 'doc-text'],
+	['application/pdf', 'doc-pdf']
 ]
 
 function getPrefixIcon(mimeType) {
@@ -76,11 +76,11 @@ function getPrefixIcon(mimeType) {
 }
 
 export function inferIcon(mimeType) {
-	if (!mimeType) return 'i-lucide:file'
+	if (!mimeType) return 'doc-default'
 	const prefixIcon = getPrefixIcon(mimeType)
 	if (prefixIcon) return prefixIcon
-	if (ARCHIVE_TYPES.has(mimeType)) return 'i-lucide:archive'
-	return 'i-lucide:file'
+	if (ARCHIVE_TYPES.has(mimeType)) return 'doc-archive'
+	return 'doc-default'
 }
 
 /**