@makolabs/ripple 2.5.9 → 3.0.0

package/dist/forms/form-types.d.ts

@@ -4,92 +4,297 @@ import type { Component } from 'svelte';
 import type { DOMAttributes } from 'svelte/elements';
 import type { SuperForm } from 'sveltekit-superforms';
 import type { VariantColors, VariantSizes } from '../index.js';
+/**
+ * Props for `<Form>` — a thin wrapper around a native `<form>` that wires
+ * in a [sveltekit-superforms](https://superforms.rocks) `SuperForm`
+ * instance and exposes its enhance/delayed helpers to child inputs.
+ *
+ * Use Form when you want validation, progressive enhancement, and the
+ * `Input`/`Checkbox`/`Toggle` helpers to read error state automatically.
+ * Skip Form if you're assembling a simple filter bar or uncontrolled UI.
+ *
+ * @example
+ * ```svelte
+ * <script lang="ts">
+ *   import { Form, Input, Button } from '@makolabs/ripple';
+ *   import { superForm } from 'sveltekit-superforms';
+ *   export let data;
+ *   const form = superForm(data.form);
+ * </script>
+ *
+ * <Form {form} method="POST">
+ *   <Input name="email" label="Email" />
+ *   <Button type="submit">Save</Button>
+ * </Form>
+ * ```
+ */
 export interface FormProps<T extends Record<string, unknown>> {
+    /** Result of `superForm(data.form)`. Drives validation + progressive enhancement. */
     form: SuperForm<any>;
     class?: ClassValue;
+    /** HTTP method on the underlying `<form>`. @default 'POST' */
     method?: 'GET' | 'POST' | 'dialog' | 'get' | 'post' | 'DIALOG' | null | undefined;
+    /** Where to post. Defaults to the current route (SvelteKit convention). */
     action?: string;
+    /** Matches the native `enctype` attribute. Use `'multipart/form-data'` for file uploads. */
     enctype?: 'application/x-www-form-urlencoded' | 'multipart/form-data' | 'text/plain' | null | undefined;
+    /** Autofill hint for the whole form. @default 'on' (browser default) */
     autocomplete?: 'on' | 'off';
+    /** Suppress native HTML5 validation; lean on superforms / server errors instead. */
     novalidate?: boolean;
+    /** Form content — typically `<Input>`/`<Checkbox>`/`<Button>` children. */
     children?: Snippet;
     testId?: string;
 }
+/**
+ * Props for `<Input>` — a styled wrapper around `<input>` (and `<textarea>`
+ * when `type='textarea'`). Supports labels, validation errors, size
+ * variants, and all native input attributes via rest props.
+ *
+ * Prefer `<Textarea>` for multi-line input — it exposes richer options
+ * (autoGrow, maxLength + counter). Keep `<Input type='textarea'>` for
+ * simple cases where Input's wider API is enough.
+ *
+ * @example
+ * ```svelte
+ * <Input name="email" type="email" label="Email" bind:value={email} required />
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <!-- With validation errors -->
+ * <Input
+ *   name="username"
+ *   bind:value={username}
+ *   errors={['Already taken']}
+ * />
+ * ```
+ */
 export type InputProps = {
+    /** @default 'text' */
     type?: 'text' | 'email' | 'password' | 'number' | 'tel' | 'url' | 'date' | 'textarea';
+    /** Bindable input value. */
     value?: string | number;
+    /** Input name. Also used as `id` if one isn't supplied. */
     name: string;
+    /** Optional label rendered above the input. */
     label?: string;
     placeholder?: string;
     required?: boolean;
     disabled?: boolean;
     class?: ClassValue;
     size?: VariantSizes;
+    /** Explicit `id`. Falls back to `name`. */
     id?: string;
+    /** Validation error messages. When non-empty, the input gets a danger border. */
     errors?: string[];
     testId?: string;
 } & DOMAttributes<HTMLInputElement>;
+/**
+ * Single option for `<RadioGroup>` (and the fused `<SegmentedControl>`,
+ * which extends it).
+ */
 export type RadioOption = {
+    /** Underlying form value — what you bind to. */
     value: string;
+    /** Visible text. */
     label: string;
+    /** Short helper text shown under the label. */
+    description?: string;
+    disabled?: boolean;
 };
+/**
+ * Props for `<RadioGroup>` — a set of mutually-exclusive radio buttons.
+ * Reach for this when the options are short and should stay visible
+ * (3-5 items); use `<Select>` or `<ComboBox>` for longer lists.
+ *
+ * @example
+ * ```svelte
+ * <RadioGroup
+ *   name="plan"
+ *   label="Choose a plan"
+ *   bind:value={plan}
+ *   options={[
+ *     { value: 'free', label: 'Free' },
+ *     { value: 'pro', label: 'Pro', description: '$10/mo' }
+ *   ]}
+ * />
+ * ```
+ */
+export interface RadioGroupProps {
+    name: string;
+    label?: string;
+    options: RadioOption[];
+    /** Bindable selected option value. */
+    value?: string;
+    disabled?: boolean;
+    required?: boolean;
+    /** Stack vertically or horizontally. @default 'vertical' */
+    orientation?: 'vertical' | 'horizontal';
+    size?: VariantSizes;
+    /** Color for the selected dot. @default 'primary' */
+    color?: VariantColors;
+    errors?: string[];
+    class?: ClassValue;
+    /** Fires whenever the selection changes. */
+    onchange?: (value: string) => void;
+    testId?: string;
+}
+/**
+ * Props for `<Checkbox>` — a single boolean toggle. Use `<Toggle>` for
+ * "on/off" UX (feature switches), and Checkbox for "selected/not selected"
+ * UX (filters, agreements, list item selection).
+ *
+ * @example
+ * ```svelte
+ * <Checkbox name="terms" label="I accept the terms" bind:value={accepted} required />
+ * ```
+ */
 export type CheckboxProps = {
     name: string;
     label?: string;
+    /** Bindable checked state. */
     value?: boolean;
     disabled?: boolean;
     class?: ClassValue;
     size?: VariantSizes;
+    /** Checked-state fill color. @default 'primary' */
     color?: VariantColors;
     errors?: string[];
     required?: boolean;
     testId?: string;
 };
+/**
+ * Props for `<Toggle>` — a binary switch for on/off states.
+ * Prefer Toggle for settings / features you're turning on and off.
+ * Prefer `<Checkbox>` for selection / agreement semantics.
+ *
+ * @example
+ * ```svelte
+ * <Toggle name="notifications" label="Email notifications" bind:value={enabled} />
+ * ```
+ */
 export interface ToggleProps {
     name: string;
     label?: string;
     disabled?: boolean;
     class?: ClassValue;
+    /** Bindable on/off state. */
     value?: boolean;
     size?: VariantSizes;
+    /**
+     * Color used when the toggle is ON. Takes precedence over
+     * `activeColor` / `offColor` when set.
+     */
     color?: VariantColors;
     id?: string;
     errors?: string[];
+    /**
+     * Raw Tailwind class for the track when OFF. Use for ad-hoc styling
+     * that doesn't map to a ripple color. @default 'bg-default-200'
+     */
     offColor?: string;
-    onColor?: string;
+    /**
+     * Raw Tailwind class for the track when ON. Overrides the default
+     * derived from `color`. Use when you need a brand-specific tint.
+     */
+    activeColor?: string;
     testId?: string;
 }
+/**
+ * A selectable currency / unit option inside `<NumberInput>`'s unit
+ * dropdown.
+ */
 export type CurrencyOption = {
+    /** The unit code/label stored as the selected unit (e.g. 'USD', '%'). */
     value: string;
+    /** Optional icon rendered in the dropdown and trigger (e.g. a flag). */
     icon?: Component;
 };
+/**
+ * Props for `<NumberInput>` — a numeric input with an optional unit
+ * selector on the right. Great for currency amounts, percentages, or
+ * anything that pairs a number with a unit.
+ *
+ * @example
+ * ```svelte
+ * <NumberInput
+ *   name="amount"
+ *   label="Amount"
+ *   bind:value={amount}
+ *   unit="USD"
+ *   units={[{ value: 'USD' }, { value: 'EUR' }, { value: 'GBP' }]}
+ *   onunitchange={(prev, next) => console.log('changed from', prev, 'to', next)}
+ * />
+ * ```
+ */
 export type NumberInputProps = {
+    /** Bindable numeric value. */
     value?: number;
     name?: string;
     label?: string;
     placeholder?: string;
     size?: VariantSizes;
     class?: ClassValue;
+    /**
+     * Currently selected unit. When `units` is provided, this doubles as
+     * the controlled value of the unit dropdown.
+     */
     unit?: string;
+    /**
+     * Available units. When set, a dropdown appears on the right side
+     * of the field. Omit to render as a plain number input.
+     */
     units?: CurrencyOption[];
     errors?: string[];
     disabled?: boolean;
-    dropdownicon?: Component;
+    /** Icon for the dropdown trigger. Defaults to a chevron. */
+    dropdownIcon?: Component;
+    /** Fires when the user picks a different unit. */
     onunitchange?: (prevUnit: string, newUnit: string) => void;
     testId?: string;
 };
+/**
+ * Props for `<DateRange>` — a two-date picker (from → to). Presents
+ * an inline calendar with both dates visually connected. For a single
+ * date use `<DatePicker>`.
+ *
+ * @example
+ * ```svelte
+ * <DateRange
+ *   startDate={from}
+ *   endDate={to}
+ *   onselect={({ startDate, endDate }) => {
+ *     from = startDate;
+ *     to = endDate;
+ *   }}
+ * />
+ * ```
+ */
 export interface DateRangeProps {
+    /** Selected start of the range. */
     startDate?: Date;
+    /** Selected end of the range. */
     endDate?: Date;
+    /** Earliest selectable date (inclusive). */
     minDate?: Date;
+    /** Latest selectable date (inclusive). */
     maxDate?: Date;
     disabled?: boolean;
     class?: ClassValue;
     placeholder?: string;
     startLabel?: string;
     endLabel?: string;
+    /**
+     * Display format for the input text. Supports `yyyy`, `MM`, `dd`
+     * tokens with any literal separator. @default 'yyyy-MM-dd'
+     */
     format?: string;
     errors?: string[];
+    /**
+     * Fires when the user completes a selection. Both dates may be
+     * undefined (cleared).
+     */
     onselect?: ({ startDate, endDate }: {
         startDate?: Date;
         endDate?: Date;
@@ -98,11 +303,32 @@ export interface DateRangeProps {
     name?: string;
     testId?: string;
 }
+/**
+ * Shape emitted by Calendar/DateRange-related selection events. `null`
+ * indicates the field was cleared rather than picked.
+ */
 export interface DateSelectEvent {
     startDate: Date | null;
     endDate: Date | null;
 }
+/**
+ * Props for `<Tags>` — an input that accepts a list of short strings
+ * (email addresses, keywords, filter terms). Users type + press Enter to
+ * add a tag; they remove tags with ×.
+ *
+ * @example
+ * ```svelte
+ * <Tags
+ *   name="recipients"
+ *   label="Recipients"
+ *   bind:value={emails}
+ *   placeholder="Add an email and press Enter"
+ *   suggestions={recentContacts}
+ * />
+ * ```
+ */
 export type TagsProps = {
+    /** Bindable array of tag strings. */
     value?: string[];
     name?: string;
     label?: string;
@@ -110,63 +336,256 @@ export type TagsProps = {
     placeholder?: string;
     size?: VariantSizes;
     class?: ClassValue;
+    /**
+     * Optional list of autocomplete suggestions shown in a dropdown
+     * while the user is typing. Tags the user has already added are
+     * filtered out of the suggestion list.
+     */
     suggestions?: string[];
+    /** Fires when a tag is added. */
     onaddtag?: (tag: string) => void;
+    /** Fires when a tag is removed (via × or backspace). */
     onremovetag?: (tag: string) => void;
     testId?: string;
 };
+/** Selection mode for `<Slider>`. */
 export type SliderMode = 'single' | 'range' | 'enum';
+/**
+ * Intl.NumberFormat notation style. Controls how the Slider renders
+ * numeric values (e.g. `compact` → "1.2K").
+ */
 export type NotationType = 'standard' | 'compact' | 'scientific' | 'engineering';
+/** Single option for Slider's enum mode — a discrete, labeled step. */
 export type EnumOption = {
     value: string | number;
     label: string;
 };
+/** Single tick mark on the Slider track. */
+export type SliderTick = {
+    /** Position on the axis. Ignored if outside `[min, max]`. */
+    value: number;
+    /** Optional text shown below the tick. */
+    label?: string;
+};
+/**
+ * Props for `<Textarea>` — a multi-line text input with optional
+ * auto-grow and character counter. Prefer this over `<Input type='textarea'>`
+ * when you need autoGrow, maxLength with counter, or richer multi-line UX.
+ *
+ * @example
+ * ```svelte
+ * <Textarea name="bio" label="Short bio" bind:value={bio} maxLength={160} showCount />
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <!-- Auto-grow up to 10 rows for chat-style composers -->
+ * <Textarea name="message" rows={1} autoGrow maxRows={10} bind:value={message} />
+ * ```
+ */
+export interface TextareaProps {
+    name: string;
+    id?: string;
+    label?: string;
+    placeholder?: string;
+    /** Bindable text value. */
+    value?: string;
+    disabled?: boolean;
+    readonly?: boolean;
+    /** Visible row count. @default 3 */
+    rows?: number;
+    /**
+     * When true, textarea height grows with content up to `maxRows` rows.
+     * @default false
+     */
+    autoGrow?: boolean;
+    /** Upper bound for autoGrow. @default 10 */
+    maxRows?: number;
+    /** Max characters. Also displays a character counter if `showCount` is true. */
+    maxLength?: number;
+    /** Show a "N / maxLength" counter under the field. Requires `maxLength`. @default false */
+    showCount?: boolean;
+    size?: VariantSizes;
+    errors?: string[];
+    class?: ClassValue;
+    /** Fires on every keystroke with the current value. */
+    oninput?: (value: string) => void;
+    /** Fires on blur with the current value. */
+    onblur?: (value: string) => void;
+    testId?: string;
+}
+/**
+ * Props for `<Slider>` — a unified slider supporting three modes:
+ * - **`single`** (default): one value. Bind to `value`.
+ * - **`range`**: two values. Bind to `valueStart` + `valueEnd`.
+ * - **`enum`**: pick from discrete `options`. Bind to `value`.
+ *
+ * Use `tickInterval` or `ticks` to render visual anchors along the
+ * track — see the examples.
+ *
+ * @example
+ * ```svelte
+ * <!-- Single value with compact formatting -->
+ * <Slider
+ *   name="volume"
+ *   label="Volume"
+ *   min={0}
+ *   max={100}
+ *   bind:value
+ *   valueSuffix="%"
+ * />
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <!-- Range with labeled ticks -->
+ * <Slider
+ *   name="budget"
+ *   mode="range"
+ *   min={0}
+ *   max={1000}
+ *   step={50}
+ *   bind:valueStart
+ *   bind:valueEnd
+ *   ticks={[
+ *     { value: 0, label: '$0' },
+ *     { value: 500, label: '$500' },
+ *     { value: 1000, label: '$1K' }
+ *   ]}
+ * />
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <!-- Discrete enum values -->
+ * <Slider
+ *   name="quality"
+ *   mode="enum"
+ *   bind:value
+ *   options={[
+ *     { value: 'low', label: 'Low' },
+ *     { value: 'med', label: 'Med' },
+ *     { value: 'high', label: 'High' }
+ *   ]}
+ * />
+ * ```
+ */
 export interface SliderProps {
     name: string;
     label?: string;
+    /** @default 'single' */
     mode?: SliderMode;
     disabled?: boolean;
     size?: VariantSizes;
     errors?: string[];
     class?: ClassValue;
+    /** Lower bound (single/range mode). @default 0 */
     min?: number;
+    /** Upper bound (single/range mode). @default 100 */
     max?: number;
+    /** Increment per arrow-key / drag step. @default 1 */
     step?: number;
+    /** Bindable value (single/enum mode). */
     value?: number | string;
+    /** Bindable range start (range mode only). */
     valueStart?: number;
+    /** Bindable range end (range mode only). */
     valueEnd?: number;
+    /** Render the formatted value alongside the label. @default true */
     showValue?: boolean;
+    /** Prefix prepended to displayed values (e.g. `'$'`). */
     valuePrefix?: string;
+    /** Suffix appended to displayed values (e.g. `' %'`). */
     valueSuffix?: string;
+    /** Required in `enum` mode — the discrete choices. */
     options?: EnumOption[];
+    /**
+     * Intl.NumberFormat options applied when rendering the value. Use
+     * `{ notation: 'compact' }` to show "1.2K" instead of "1200".
+     */
     formatOptions?: Intl.NumberFormatOptions & {
         notation?: NotationType;
     };
+    /**
+     * Draw a tick mark at every multiple of this interval between `min` and
+     * `max`. Ignored in `enum` mode (options already act as ticks). Ignored
+     * if `ticks` is also set.
+     */
+    tickInterval?: number;
+    /**
+     * Explicit tick marks with optional labels. Overrides `tickInterval`.
+     * Values outside `[min, max]` are ignored.
+     */
+    ticks?: Array<number | SliderTick>;
     testId?: string;
 }
-/** Single segment in a fused SegmentedControl bar (not TabGroup — no panels). */
+/**
+ * Single segment in a fused `<SegmentedControl>` bar — extends
+ * `RadioOption` with visual embellishments (prefix icon, HTML title).
+ * Unlike `TabGroup`, segments are purely a control (no panels).
+ */
 export type SegmentedOption = RadioOption & {
-    /** Shown before label, e.g. flag emoji */
+    /** Content rendered before the label (e.g. flag emoji, icon). */
     prefix?: string;
-    /** `title` on the segment button */
+    /** Native `title` attribute on the segment button (hover tooltip). */
     title?: string;
     disabled?: boolean;
 };
+/**
+ * Props for `<SegmentedControl>` — a compact segmented radio control
+ * (think iOS segmented control). Use for 2-5 mutually-exclusive short
+ * options where visibility matters more than listing space.
+ *
+ * Differences vs related components:
+ * - `<RadioGroup>` — more vertical space, option descriptions allowed
+ * - `<TabGroup>` — tabs with associated panel content below
+ *
+ * @example
+ * ```svelte
+ * <SegmentedControl
+ *   name="view"
+ *   label="View as"
+ *   bind:value
+ *   options={[
+ *     { value: 'list', label: 'List' },
+ *     { value: 'grid', label: 'Grid' },
+ *     { value: 'kanban', label: 'Kanban' }
+ *   ]}
+ * />
+ * ```
+ */
 export type SegmentedControlProps = {
     options: SegmentedOption[];
+    /** Bindable selected value. */
     value?: string;
     name?: string;
     label?: string;
     class?: ClassValue;
+    /**
+     * Visual treatment:
+     * - `'surface'` (default) — segments sit in a contrasting track
+     * - `'inverted'` — track is white, selected segment is colored
+     * - `'pills'` — detached pill-shaped segments with a subtle outline
+     */
     appearance?: 'surface' | 'inverted' | 'pills';
-    orientation?: 'horizontal' | 'vertical';
+    /**
+     * - `'horizontal'` (default) — items in a row.
+     * - `'vertical'` — items stacked.
+     * - `'auto'` — horizontal by default, flips to vertical when the parent
+     *   container drops below 250px (uses CSS container queries, no JS).
+     */
+    orientation?: 'horizontal' | 'vertical' | 'auto';
     color?: VariantColors;
     size?: VariantSizes;
+    /** Tighten horizontal padding to fit more segments in narrow space. */
     compact?: boolean;
+    /** Label placement relative to the control. @default 'above' */
     labelLayout?: 'above' | 'inline';
+    /** Additional classes for the label element. */
     labelClass?: ClassValue;
     disabled?: boolean;
     errors?: string[];
+    /** Fires on selection change with the new value. */
     onchange?: (value: string) => void;
     testId?: string;
 };

package/dist/forms/market/market-selector-types.d.ts

@@ -1,22 +1,73 @@
 import type { ClassValue } from 'tailwind-variants';
 import type { CountryCode } from './country-data.js';
 import type { VariantColors, VariantSizes } from '../../index.js';
+/**
+ * Props for `<MarketSelector>` — a specialised `<SegmentedControl>` for
+ * picking between a small set of geographic markets. Renders a flag +
+ * country code per segment, and can collapse to flags-only in narrow
+ * layouts (sidebar rails, mobile).
+ *
+ * @example
+ * ```svelte
+ * <MarketSelector
+ *   markets={['US', 'GB', 'FR', 'DE']}
+ *   selectedMarket={market}
+ *   onchange={(code) => (market = code)}
+ * />
+ * ```
+ *
+ * @example
+ * ```svelte
+ * <!-- Auto-collapse to flags-only on narrow screens -->
+ * <MarketSelector
+ *   markets={['US', 'EU', 'JP']}
+ *   orientation="auto"
+ *   flagsOnly={collapsed}
+ *   bind:selectedMarket
+ * />
+ * ```
+ */
 export type MarketSelectorProps = {
+    /** Ordered list of market codes to render as segments. */
     markets: CountryCode[];
+    /** Bindable currently-selected market code. */
     selectedMarket?: CountryCode;
+    /**
+     * Market to fall back to when `selectedMarket` is undefined on first
+     * render. Defaults to the first entry in `markets`.
+     */
     defaultMarket?: CountryCode;
+    /** Render a flag emoji before each label. @default true */
     showFlags?: boolean;
     label?: string;
+    /**
+     * Visual treatment — see `SegmentedControl.appearance`.
+     * @default 'surface'
+     */
     appearance?: 'surface' | 'inverted' | 'pills';
-    orientation?: 'horizontal' | 'vertical';
+    /**
+     * - `'horizontal'` — items in a row.
+     * - `'vertical'` — items stacked.
+     * - `'auto'` (default) — flips to vertical when the parent container drops below 250px.
+     */
+    orientation?: 'horizontal' | 'vertical' | 'auto';
+    /** Label placement relative to the control. @default 'above' */
     labelLayout?: 'above' | 'inline';
     labelClass?: ClassValue;
     color?: VariantColors;
     size?: VariantSizes;
+    /** Tighten horizontal padding to fit more segments in narrow space. */
     compact?: boolean;
+    /**
+     * Hide country code labels and show only flag emojis. Implies `showFlags: true`.
+     * Useful in narrow spaces like a collapsed sidebar. @default false
+     */
+    flagsOnly?: boolean;
     disabled?: boolean;
     class?: ClassValue;
+    /** Form name attribute on the hidden input (for native POST submissions). */
     name?: string;
+    /** Fires when the user picks a different market. */
     onchange?: (market: CountryCode) => void;
     testId?: string;
 };

package/dist/forms/segmented-control.d.ts

@@ -10,8 +10,9 @@ export declare const segmentedTrack: import("tailwind-variants").TVReturnType<{
     orientation: {
         horizontal: string;
         vertical: string;
+        auto: string;
     };
-}, undefined, "inline-flex overflow-hidden rounded-lg border", {
+}, undefined, "inline-flex max-w-full overflow-x-auto rounded-lg border [scrollbar-width:none] [&::-webkit-scrollbar]:hidden", {
     appearance: {
         surface: string;
         inverted: string;
@@ -20,6 +21,7 @@ export declare const segmentedTrack: import("tailwind-variants").TVReturnType<{
     orientation: {
         horizontal: string;
         vertical: string;
+        auto: string;
     };
 }, undefined, import("tailwind-variants").TVReturnType<{
     appearance: {
@@ -30,8 +32,9 @@ export declare const segmentedTrack: import("tailwind-variants").TVReturnType<{
     orientation: {
         horizontal: string;
         vertical: string;
+        auto: string;
     };
-}, undefined, "inline-flex overflow-hidden rounded-lg border", unknown, unknown, undefined>>;
+}, undefined, "inline-flex max-w-full overflow-x-auto rounded-lg border [scrollbar-width:none] [&::-webkit-scrollbar]:hidden", unknown, unknown, undefined>>;
 export declare function segmentClasses(args: {
     selected: boolean;
     disabled: boolean;