@spaethtech/svelte-ui 0.1.10 → 0.3.1-dev.10.ff03a8d

package/dist/types/breakpoints.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Responsive breakpoint tiers — the single source of truth for any
+ * component that accepts per-tier configuration (modes, columns,
+ * visibility, etc.). Keys match the tier names defined in
+ * `theme.css`, with `base` for the unconditional "no min-width" case.
+ *
+ * Pixel widths are exposed alongside the type so JS-driven mode
+ * resolution (via matchMedia) can stay in sync with the CSS without
+ * a second source of truth.
+ *
+ *  - `base` → 0 px (no min-width — the unconditional fallback)
+ *  - `4xs`  → 320 px (iPhone SE class)
+ *  - `3xs`  → 360 px (narrow Android)
+ *  - `2xs`  → 420 px (standard phone)
+ *  - `xs`   → 480 px (large phone / small tablet portrait)
+ *  - `sm`   → 640 px (Tailwind default)
+ *  - `md`   → 768 px (Tailwind default)
+ *  - `lg`   → 1024 px (Tailwind default)
+ *  - `xl`   → 1280 px (Tailwind default)
+ *  - `2xl`  → 1536 px (Tailwind default)
+ *  - `3xl`  → 1920 px (FHD / 1080p ultrawide)
+ */
+export type Breakpoint = "base" | "4xs" | "3xs" | "2xs" | "xs" | "sm" | "md" | "lg" | "xl" | "2xl" | "3xl";
+export declare const BREAKPOINT_PX: Record<Breakpoint, number>;

package/dist/types/breakpoints.js

@@ -0,0 +1,13 @@
+export const BREAKPOINT_PX = {
+    base: 0,
+    "4xs": 320,
+    "3xs": 360,
+    "2xs": 420,
+    xs: 480,
+    sm: 640,
+    md: 768,
+    lg: 1024,
+    xl: 1280,
+    "2xl": 1536,
+    "3xl": 1920,
+};

package/dist/types/responsive.d.ts

@@ -0,0 +1,32 @@
+import { type Breakpoint } from "./breakpoints.js";
+/**
+ * A value that is either a single `T` (applied at every width) OR a per-breakpoint map.
+ * Mobile-first: `base` (or a bare `T`) is the unconditional value; each larger tier present in the
+ * map overrides from its min-width upward. Mirrors the DataTable column `breakpoints` shape so the
+ * whole library speaks one responsive language.
+ *
+ *   size="lg"                          // always lg
+ *   size={{ base: 'lg', xs: 'md' }}    // lg on phones, md at >=480px
+ */
+export type Responsive<T extends string> = T | Partial<Record<Breakpoint, T>>;
+/**
+ * Resolve a `Responsive<T>` into a Tailwind class string, given a per-value class map.
+ *
+ * - Scalar `T` → the map entry verbatim (today's behaviour, zero overhead).
+ * - Map → the `base` entry unprefixed, then each higher tier's entry with its `bp:` prefix applied
+ *   to EVERY class token (`'h-8 px-4'` at `xs` → `'xs:h-8 xs:px-4'`). Emitted low→high min-width so
+ *   the CSS cascade lands on the active tier. Works for arbitrary/variant tokens too — the prefix
+ *   sits in front of the whole chain (`xs:[&_svg]:w-4`, `xs:[background-color:var(--x)]`).
+ *
+ * The generated `bp:`-prefixed classes are runtime strings Tailwind can't see by scanning source —
+ * they are safelisted via `@source inline` in `theme.css` (see the `-- responsive size/variant --`
+ * block there); consuming apps inherit it through `@import 'svelte-ui/theme.css'`.
+ */
+export declare function responsiveClasses<T extends string>(value: Responsive<T> | undefined, map: Record<T, string>): string;
+/**
+ * Collapse a `Responsive<T>` to a single scalar — for the rare bits driven by JS/inline-style rather
+ * than a class (e.g. a numeric line-height for autosize math, or a CSS-var set via `style=`). Scalar
+ * passes through; a map yields its `base` tier (or `fallback`). Those aspects therefore track the
+ * mobile-first tier only — the CLASS-driven visuals still respond at every breakpoint.
+ */
+export declare function resolveScalar<T extends string>(value: Responsive<T> | undefined, fallback: T): T;

package/dist/types/responsive.js

@@ -0,0 +1,54 @@
+import { BREAKPOINT_PX } from "./breakpoints.js";
+/** Breakpoints ascending by min-width — so prefixed rules emit in cascade order (larger wins). */
+const ASCENDING = Object.keys(BREAKPOINT_PX).sort((a, b) => BREAKPOINT_PX[a] - BREAKPOINT_PX[b]);
+/**
+ * Resolve a `Responsive<T>` into a Tailwind class string, given a per-value class map.
+ *
+ * - Scalar `T` → the map entry verbatim (today's behaviour, zero overhead).
+ * - Map → the `base` entry unprefixed, then each higher tier's entry with its `bp:` prefix applied
+ *   to EVERY class token (`'h-8 px-4'` at `xs` → `'xs:h-8 xs:px-4'`). Emitted low→high min-width so
+ *   the CSS cascade lands on the active tier. Works for arbitrary/variant tokens too — the prefix
+ *   sits in front of the whole chain (`xs:[&_svg]:w-4`, `xs:[background-color:var(--x)]`).
+ *
+ * The generated `bp:`-prefixed classes are runtime strings Tailwind can't see by scanning source —
+ * they are safelisted via `@source inline` in `theme.css` (see the `-- responsive size/variant --`
+ * block there); consuming apps inherit it through `@import 'svelte-ui/theme.css'`.
+ */
+export function responsiveClasses(value, map) {
+    if (value == null)
+        return "";
+    if (typeof value === "string")
+        return map[value] ?? "";
+    let out = "";
+    for (const bp of ASCENDING) {
+        const tier = value[bp];
+        if (tier == null)
+            continue;
+        const cls = map[tier];
+        if (!cls)
+            continue;
+        out += out ? " " : "";
+        out +=
+            bp === "base"
+                ? cls
+                : cls
+                    .trim()
+                    .split(/\s+/)
+                    .map((t) => `${bp}:${t}`)
+                    .join(" ");
+    }
+    return out;
+}
+/**
+ * Collapse a `Responsive<T>` to a single scalar — for the rare bits driven by JS/inline-style rather
+ * than a class (e.g. a numeric line-height for autosize math, or a CSS-var set via `style=`). Scalar
+ * passes through; a map yields its `base` tier (or `fallback`). Those aspects therefore track the
+ * mobile-first tier only — the CLASS-driven visuals still respond at every breakpoint.
+ */
+export function resolveScalar(value, fallback) {
+    if (value == null)
+        return fallback;
+    if (typeof value === "string")
+        return value;
+    return value.base ?? fallback;
+}

package/dist/types/sizes.d.ts

@@ -1,5 +1,12 @@
 /**
- * Standard size variants used across UI components.
- * Ensures consistent heights and spacing throughout the library.
+ * Shared sizing axis — the cross-cutting counterpart to {@link ./variants.ts | Variant}.
+ * Every sizeable component (Button, Input, Select, …) accepts `size` and maps it to a consistent
+ * control height / text / padding / icon scale. Default is always `md` (today's look).
+ *
+ *  - `sm` → 24px (`--ui-height-sm`) · dense: table chrome, inline controls
+ *  - `md` → 32px (`--ui-height`)    · default
+ *  - `lg` → 40px (`--ui-height-lg`) · prominent  (0.75× / 1.0× / 1.25× around md)
+ *
+ * `--ui-height-touch` (44px) is a separate token for explicit touch targets — not `lg`.
  */
-export type Size = 'sm' | 'md' | 'lg';
+export type Size = "sm" | "md" | "lg";

package/dist/types/time.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Step interval for the time spinner columns. A bare number is shorthand for the MINUTE step (the
+ * common case); an object sets any column independently. Unspecified columns default to 1.
+ *
+ *   step={15}                          // minutes step by 15 (hours/seconds by 1)
+ *   step={{ minute: 15, second: 30 }}  // minutes by 15, seconds by 30
+ *   step={{ hour: 2 }}                 // hours by 2
+ */
+export type StepSpec = number | {
+    hour?: number;
+    minute?: number;
+    second?: number;
+};
+/** Resolve a {@link StepSpec} to a per-column `{ hour, minute, second }` (each ≥ 1). */
+export declare function resolveStep(step: StepSpec | undefined): {
+    hour: number;
+    minute: number;
+    second: number;
+};

package/dist/types/time.js

@@ -0,0 +1,10 @@
+/** Resolve a {@link StepSpec} to a per-column `{ hour, minute, second }` (each ≥ 1). */
+export function resolveStep(step) {
+    if (typeof step === "number")
+        return { hour: 1, minute: Math.max(1, step), second: 1 };
+    return {
+        hour: Math.max(1, step?.hour ?? 1),
+        minute: Math.max(1, step?.minute ?? 1),
+        second: Math.max(1, step?.second ?? 1),
+    };
+}

package/dist/types/variants.d.ts

@@ -1 +1,8 @@
-export type Variant = 'primary' | 'secondary' | 'danger' | 'info' | 'success' | 'warning' | 'ghost';
+export type Variant = "neutral" | "primary" | "secondary" | "success" | "info" | "warning" | "danger" | "ghost";
+/** Variant → semantic colour token, used where a variant needs an ACCENT colour (Toggle track,
+ *  Checkbox, Card border, DataTable accent…). `danger` maps to `--ui-color-error`. The two non-accent
+ *  variants — `ghost` (transparent, hover-tint only) and `neutral` (text-mix surface tint, = the
+ *  default DataTable look) — resolve to `--ui-color-text`, so those controls read grey/uncoloured
+ *  rather than borrowing an accent. The interactive tints (hover/surface/active) are text-mixes by
+ *  default and re-mix off whichever colour this points at. */
+export declare const variantToken: Record<Variant, string>;

package/dist/types/variants.js

@@ -1 +1,16 @@
-export {};
+/** Variant → semantic colour token, used where a variant needs an ACCENT colour (Toggle track,
+ *  Checkbox, Card border, DataTable accent…). `danger` maps to `--ui-color-error`. The two non-accent
+ *  variants — `ghost` (transparent, hover-tint only) and `neutral` (text-mix surface tint, = the
+ *  default DataTable look) — resolve to `--ui-color-text`, so those controls read grey/uncoloured
+ *  rather than borrowing an accent. The interactive tints (hover/surface/active) are text-mixes by
+ *  default and re-mix off whichever colour this points at. */
+export const variantToken = {
+    neutral: "--ui-color-text",
+    primary: "--ui-color-primary",
+    secondary: "--ui-color-secondary",
+    success: "--ui-color-success",
+    info: "--ui-color-info",
+    warning: "--ui-color-warning",
+    danger: "--ui-color-error",
+    ghost: "--ui-color-text",
+};

package/docs/components.md

@@ -0,0 +1,255 @@
+# Component Reference
+
+Complete reference for all svelte-ui components. The exported set is whatever
+`src/lib/index.ts` re-exports — this doc tracks it.
+
+Icons are **MDI via `unplugin-icons`** — there is **no `Icon` component**. You render an icon by
+importing an MDI component (`import IconHome from '~icons/mdi/home'`) and passing it into a
+component's `icon` **snippet**. See `docs/usage.md`.
+
+## Cross-cutting axes
+
+Most sizeable/themeable components share two props (defined in `types/variants.ts` /
+`types/sizes.ts`):
+
+- **`variant`** — color/style: `primary`, `secondary`, `danger`, `info`, `success`, `warning`,
+  `ghost`, `plain`. `plain` is borderless/transparent — for dense icon controls.
+- **`size`** — `sm` (24px), `md` (32px, **default**), `lg` (40px). Tied to the theme's
+  `--ui-height-sm` / `--ui-height` / `--ui-height-lg`.
+
+## Form Components
+
+### Button
+
+Flexible button/anchor component.
+
+- **Location**: `src/lib/components/Button.svelte`
+- **Axes**: `variant`, `size`
+- **Props**: `text`, `icon` (snippet), `href` (renders an `<a>`), `disabled`, `onclick`, `title`,
+  plus native button/anchor attributes
+- **Features**: icon-only sizing, themed tooltip driven from `title` (via `use:tooltip`),
+  TypeScript discriminated union for button-vs-anchor
+- **Accessibility**: ARIA attributes, focus-visible outlines
+
+### Input
+
+Text input with an icon slot, trailing actions, and validation.
+
+- **Location**: `src/lib/components/Input.svelte`
+- **Axes**: `size`
+- **Props**: `value` (bindable), `icon` (snippet), `iconPosition` (`'left' | 'right'`, default
+  `'right'`), `iconClickable`, `onIconClick`, `actions` (snippet — trailing controls inside the
+  frame), `validate`, `valid`/`touched` (bindable), plus native input attributes
+- **Note**: a single `icon` snippet positioned by `iconPosition` — there is no
+  `iconLeft`/`iconRight`.
+
+### Select
+
+Custom dropdown built on `Input` + `List`.
+
+- **Location**: `src/lib/components/Select.svelte`
+- **Axes**: `size`
+- **Props**: `options` (`{ value, label, ... }[]`), `value` (bindable), `multiSelect`,
+  `placeholder`, `itemSnippet`, plus API props (`url`, `searchParam`, `transform`, `debounceMs`,
+  `maxResults`, `headers`, `searchTerm`)
+- **Modes**: static `options` or search-as-you-type against `url`
+
+### List
+
+Standalone selectable list (Select's dropdown body).
+
+- **Location**: `src/lib/components/List.svelte`
+- **Axes**: `size`
+- **Props**: `options` (`{ value, label, ... }[]`), `value` (bindable), `multiSelect`,
+  `showCheckboxes`, `maxVisibleItems`, `itemSnippet`, plus the same API props as `Select`
+
+### TextArea
+
+Multi-line text input with optional auto-resize.
+
+- **Location**: `src/lib/components/TextArea.svelte`
+- **Axes**: `size`
+- **Props**: `value` (bindable), `minRows`, `maxRows`, `lineHeightRem`, `allowCopy` (built-in copy
+  control), `validate`, `valid`/`touched`, plus native textarea attributes
+- **Modes**: fixed height (`minRows === maxRows`) or auto-sizing
+
+### Checkbox
+
+Small themed checkbox (native control tinted via `accent-color`).
+
+- **Location**: `src/lib/components/Checkbox.svelte`
+- **Axes**: `size`
+- **Props**: `checked` (bindable), `indeterminate`, `disabled`, plus native input attributes
+
+### Rating
+
+Read-only star-rating display (5-star, from a 10-point average).
+
+- **Location**: `src/lib/components/Rating.svelte`
+- **Props**: `average` (number), `count` (number)
+
+## Specialized Input Components
+
+Thin wrappers over `Input`, each preconfigured with an MDI icon (rendered into Input's snippet).
+
+### PasswordInput
+
+- **Location**: `src/lib/components/PasswordInput.svelte`
+- **Features**: built-in visibility toggle (eye / eye-off MDI icons)
+
+### EmailInput
+
+- **Location**: `src/lib/components/EmailInput.svelte`
+- **Features**: email validation, envelope icon
+
+### SearchInput
+
+- **Location**: `src/lib/components/SearchInput.svelte`
+- **Features**: search (magnify) icon, clear button when typing
+
+### NumberInput
+
+- **Location**: `src/lib/components/NumberInput.svelte`
+- **Features**: number formatting and validation
+
+## Data Components
+
+These pair with the headless **`@spaethtech/svelte-ui/data`** layer (query-language parser/AST, `createGrid`,
+`DataSet`). See `docs/usage.md`.
+
+### DataTable
+
+Config-driven, responsive 12-column data table over a `DataGrid`.
+
+- **Location**: `src/lib/components/DataTable.svelte`
+- **Props**: `grid` (`DataGrid<T>` from `@spaethtech/svelte-ui/data`), `selectable`, `expandable`, `expanded`
+  (snippet), `rowActions` (`(row) => MenuItem[]`), `bulkActions`
+- **Features**: selectable + expandable rows, sortable headers, per-row & bulk action menus
+  (via `Menu`/`Popup`), paginated footer. A **compound component** — all controls are
+  `<Button variant="plain" size="sm">` / `<Select size="sm">` / `<Checkbox>`.
+
+### Query
+
+Filter bar over a `DataSet` — monospace input with `$column` + enum-value autocomplete and a help
+dialog.
+
+- **Location**: `src/lib/components/Query.svelte`
+- **Props**: `dataset` (`DataSet`), `placeholder`
+- **Note**: URL sync is intentionally not built in — observe `dataset.applied` and sync yourself.
+  Built on `Input` + `Button` + `Popup` + `Dialog`.
+
+## Overlays
+
+### Dialog
+
+**Pure modal shell** — the mechanics only, no imposed content. Put a `Card` (or anything) inside via
+`children`. For the common confirm pattern use `ConfirmDialog` (below).
+
+- **Location**: `src/lib/components/Dialog.svelte`
+- **Props**: `isOpen` (bindable), `width` (any CSS value — `'80%'`, `'80vw'`, `'400px'`; default
+  auto, capped at `min(32rem, …)`), `height` (any CSS value; default auto), `dismissible` (default
+  `true`), `onClose`, `class`, `children` (snippet). Extra attributes (e.g. `aria-label`) spread onto
+  the panel.
+- **Features**: portals to `<body>`, background scroll-lock (scrollbar-width compensated), backdrop
+  + Escape dismiss, **focus trap** (initial focus in, Tab wraps, focus restored on close),
+  `role="dialog"` + `aria-modal`.
+
+### ConfirmDialog
+
+The common title + message + Confirm/Cancel modal, composed from a `Card` on top of the `Dialog`
+shell.
+
+- **Location**: `src/lib/components/ConfirmDialog.svelte`
+- **Props**: `isOpen` (bindable), `title`, `message`, `confirmText`, `cancelText`, `onConfirm`,
+  `onCancel`, `variant` (`'normal' | 'danger'`), `size`, `showConfirm`, `showCancel`, `dismissible`,
+  `width`/`height` (forwarded to the shell), `children` (snippet — replaces `message` as the body).
+
+### Popup
+
+Interactive popover anchored to a trigger, rendered in the browser top layer (Popover API) so it's
+never clipped by overflow/stacking contexts. Placement via the shared `anchored` engine.
+
+- **Location**: `src/lib/components/Popup.svelte`
+- **Props**: `anchor` (trigger element), `open` (bindable), `side`, `align`, `boundary`
+  (`'viewport'` or an element/selector), `offset`, `matchWidth`, `onclose`, `children` (snippet)
+- **Features**: flips against the boundary, dismisses on Escape + outside pointerdown
+
+### Menu
+
+Keyboard-navigable action menu rendered inside a `Popup`.
+
+- **Location**: `src/lib/components/Menu.svelte`
+- **Props**: `anchor`, `open` (bindable), `items` (`MenuItem[]` from `@spaethtech/svelte-ui/data`), `side`,
+  `align`, `boundary`
+- **Features**: renders all items always and disables the invalid ones; aligns labels when any
+  item has an icon
+
+### tooltip (action)
+
+Themed tooltips as a Svelte action — `use:tooltip` — built on `anchored`. No global handler.
+
+- **Location**: `src/lib/positioning/tooltip.ts`
+- **Options** (`TooltipOptions`): `text` (defaults to the element's `title`, which is then
+  suppressed), `side` (default `top`), `align`, `offset`, `delay`, `disabled`
+- **Note**: `Button` feeds this from its `title`, so native `title` tooltips are replaced wherever
+  a Button is used. Mirrors text to `aria-label` when the element has no accessible name.
+
+## Positioning
+
+### anchored (engine)
+
+Shared placement engine — a Svelte action plus `computePlacement` / `resolveBoundary` — used by
+`Popup`, `Menu`, and `tooltip`.
+
+- **Location**: `src/lib/positioning/anchored.ts`
+- **Exports**: `anchored`, `computePlacement`, `resolveBoundary`, and the types `Side`, `Align`,
+  `Boundary`, `PlaceOptions`, `Placement`, `AnchoredParams`
+
+## Display / Theme
+
+### Badge
+
+Status indicator / label.
+
+- **Location**: `src/lib/components/Badge/Badge.svelte`
+- **Axes**: `size`
+- **Variants**: `default`, `primary`, `success`, `warning`, `danger`, `info`
+- **Props**: `text`, `variant`, `size`, `dismissible`, `rounded`, `children`; dispatches `dismiss`
+
+### NotesEditor
+
+- **Location**: `src/lib/components/NotesEditor.svelte`
+
+### ThemeSelector
+
+Theme switcher (Auto / Light / Dark), built on `Select`.
+
+- **Location**: `src/lib/components/ThemeSelector.svelte`
+- **Features**: applies `.theme-light` / `.theme-dark` to `<html>`/`<body>`, `auto` follows the
+  system preference, persists to `localStorage` (`svelte-ui-theme`)
+
+## Import Pattern
+
+```typescript
+import { Button, Input, Select, DataTable, tooltip } from "@spaethtech/svelte-ui";
+import { createGrid } from "@spaethtech/svelte-ui/data";
+import "@spaethtech/svelte-ui/theme.css"; // via @import in your app.css
+```
+
+## Component Structure
+
+### Colocated Components
+
+```
+src/lib/components/ComponentName/
+├── ComponentName.svelte      # Implementation
+├── ComponentName.spec.md     # Specification
+├── ComponentName.test.ts     # Tests
+└── index.ts                  # Export
+```
+
+### Simple Components
+
+```
+src/lib/components/ComponentName.svelte
+```