@forthtilliath/forth-ui 0.2.4 → 0.3.0

package/README.md

@@ -8,7 +8,7 @@ built from `Popover` + `Command`, a `PasswordInput` with a strength meter, a
 `Dropdrawer` that's a `DropdownMenu` on desktop and a `Drawer` on mobile —
 so you don't have to wire the same recipe from scratch in every project.
 
-58 components across 8 categories, styled with Tailwind CSS and
+62 components across 8 categories, styled with Tailwind CSS and
 `class-variance-authority`, fully typed, and browsable in Storybook
 (`pnpm run dev:sb` from the repo root).
 
@@ -186,6 +186,7 @@ Grouped the same way as the Storybook sidebar (`forth-ui/<Category>/...`).
 | `Rating`                  | `components/rating`         | A star rating control with keyboard navigation and hover preview.        |
 | `SubmitButton`            | `components/submit-button`  | A submit `Button` that shows its own loading state via `useFormStatus`.  |
 | `TagsInput`               | `components/tags-input`     | A flexible input for adding/removing multiple tags.                      |
+| `ToggleSwitch`            | `components/toggle-switch`  | An on/off switch with an optional visible label and description.         |
 
 ### Feedback
 
@@ -211,17 +212,20 @@ Grouped the same way as the Storybook sidebar (`forth-ui/<Category>/...`).
 
 ### Data Display
 
-| Component               | Import                        | Description                                                              |
-| ----------------------- | ----------------------------- | ------------------------------------------------------------------------ |
-| `Avatar`, `AvatarGroup` | `components/avatar`           | An image with a fallback, status/badge indicators, and stacked grouping. |
-| `DescriptionList`       | `components/description-list` | A description list, with terms and descriptions.                         |
-| `FileList`              | `components/file-list`        | Displays a list of files with name, size, and upload progress.           |
-| `Kbd`                   | `components/kbd`              | Displays which key or combination of keys performs a given action.       |
-| `QrCode`                | `components/qr-code`          | Generates a QR code from a string, rendered as inline SVG.               |
-| `RelativeTime`          | `components/relative-time`    | Displays a live-updating time, defaulting to the local timezone.         |
-| `Sortable`              | `components/sortable`         | A drag-to-reorder list built on native HTML5 drag events.                |
-| `Timeline`              | `components/timeline`         | A vertical sequence of dated events, connected by a line.                |
-| `Tree`                  | `components/tree`             | A hierarchical, expandable/collapsible list of nodes.                    |
+| Component                      | Import                        | Description                                                              |
+| ------------------------------ | ----------------------------- | ------------------------------------------------------------------------ |
+| `Avatar`, `AvatarGroup`        | `components/avatar`           | An image with a fallback, status/badge indicators, and stacked grouping. |
+| `ColumnMenu` (`useDndSensors`) | `components/column-menu`      | A dropdown to show/hide and reorder (drag and drop) a table's columns.   |
+| `DescriptionList`              | `components/description-list` | A description list, with terms and descriptions.                         |
+| `FileList`                     | `components/file-list`        | Displays a list of files with name, size, and upload progress.           |
+| `GradientFrame`                | `components/gradient-frame`   | A visual laid on an offset, gradient-filled frame.                       |
+| `IconBubble`                   | `components/icon-bubble`      | An icon inside a round, tinted bubble.                                   |
+| `Kbd`                          | `components/kbd`              | Displays which key or combination of keys performs a given action.       |
+| `QrCode`                       | `components/qr-code`          | Generates a QR code from a string, rendered as inline SVG.               |
+| `RelativeTime`                 | `components/relative-time`    | Displays a live-updating time, defaulting to the local timezone.         |
+| `Sortable`                     | `components/sortable`         | A drag-to-reorder list built on native HTML5 drag events.                |
+| `Timeline`                     | `components/timeline`         | A vertical sequence of dated events, connected by a line.                |
+| `Tree`                         | `components/tree`             | A hierarchical, expandable/collapsible list of nodes.                    |
 
 ### Code & Content
 

package/dist/components/column-menu/column-menu.d.ts

@@ -0,0 +1,39 @@
+import type { ColumnMenuColumn, ColumnMenuLabels } from "./types";
+export interface ColumnMenuProps<C extends ColumnMenuColumn> {
+    columns: C[];
+    /** Restored by the reset button. */
+    defaultColumns: C[];
+    /** Receives an updater, so a `useState` setter can be passed directly. */
+    onColumnsChange: (update: (prev: C[]) => C[]) => void;
+    /** Overrides some or all of the displayed texts. */
+    labels?: Partial<ColumnMenuLabels>;
+    /** Side of the trigger the dropdown is aligned to (default: `"end"`). */
+    align?: "start" | "end";
+    /**
+     * Custom classes for each part of the component.
+     *
+     * - `root` wraps the trigger and the dropdown.
+     * - `trigger` is the toggle button.
+     * - `badge` is the "visible / total" counter inside the trigger.
+     * - `content` is the dropdown panel.
+     * - `header` is the title + reset bar.
+     * - `hint` is the usage hint under the header.
+     * - `list` wraps the rows.
+     * - `row` is applied to every column row.
+     */
+    className?: Partial<Record<"root" | "trigger" | "badge" | "content" | "header" | "hint" | "list" | "row", string>>;
+}
+/**
+ * A dropdown to show/hide and reorder (drag and drop, touch and keyboard
+ * included) the columns of a table, with a "visible / total" counter and a
+ * reset button. Closes on outside click and `Escape`.
+ *
+ * Pair it with `createColumnStorage` from `@forthtilliath/ts-kit` to persist
+ * the user's layout.
+ *
+ * @version 0.1.0
+ * @author Forth
+ * @copyright 2026 Forth
+ */
+export declare function ColumnMenu<C extends ColumnMenuColumn>({ columns, defaultColumns, onColumnsChange, labels, align, className, }: ColumnMenuProps<C>): import("react").JSX.Element;
+//# sourceMappingURL=column-menu.d.ts.map

package/dist/components/column-menu/column-menu.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"column-menu.d.ts","sourceRoot":"","sources":["../../../src/components/column-menu/column-menu.tsx"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAIlE,MAAM,WAAW,eAAe,CAAC,CAAC,SAAS,gBAAgB;IACzD,OAAO,EAAE,CAAC,EAAE,CAAC;IACb,oCAAoC;IACpC,cAAc,EAAE,CAAC,EAAE,CAAC;IACpB,0EAA0E;IAC1E,eAAe,EAAE,CAAC,MAAM,EAAE,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,CAAC,EAAE,KAAK,IAAI,CAAC;IACtD,oDAAoD;IACpD,MAAM,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,CAAC;IACnC,yEAAyE;IACzE,KAAK,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;IACxB;;;;;;;;;;;OAWG;IACH,SAAS,CAAC,EAAE,OAAO,CACjB,MAAM,CACF,MAAM,GACN,SAAS,GACT,OAAO,GACP,SAAS,GACT,QAAQ,GACR,MAAM,GACN,MAAM,GACN,KAAK,EACP,MAAM,CACP,CACF,CAAC;CACH;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,CAAC,SAAS,gBAAgB,EAAE,EACrD,OAAO,EACP,cAAc,EACd,eAAe,EACf,MAAM,EACN,KAAa,EACb,SAAS,GACV,EAAE,eAAe,CAAC,CAAC,CAAC,+BAyJpB"}

package/dist/components/column-menu/column-menu.js

@@ -0,0 +1,74 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useEffect, useId, useRef, useState } from "react";
+import { closestCenter, DndContext } from "@dnd-kit/core";
+import { arrayMove, SortableContext, verticalListSortingStrategy, } from "@dnd-kit/sortable";
+import { ChevronDown, RotateCcw } from "lucide-react";
+import { cn } from "@forthtilliath/shadcn-ui/lib/utils";
+import { SortableColumnRow } from "./sortable-column-row";
+import { DEFAULT_COLUMN_MENU_LABELS } from "./types";
+import { useDndSensors } from "./use-dnd-sensors";
+/**
+ * A dropdown to show/hide and reorder (drag and drop, touch and keyboard
+ * included) the columns of a table, with a "visible / total" counter and a
+ * reset button. Closes on outside click and `Escape`.
+ *
+ * Pair it with `createColumnStorage` from `@forthtilliath/ts-kit` to persist
+ * the user's layout.
+ *
+ * @version 0.1.0
+ * @author Forth
+ * @copyright 2026 Forth
+ */
+export function ColumnMenu({ columns, defaultColumns, onColumnsChange, labels, align = "end", className, }) {
+    const text = { ...DEFAULT_COLUMN_MENU_LABELS, ...labels };
+    // Stable id: avoids a hydration mismatch on dnd-kit's aria-describedby
+    const dndId = useId();
+    const contentId = useId();
+    const rootRef = useRef(null);
+    const [open, setOpen] = useState(false);
+    const sensors = useDndSensors();
+    const visibleCount = columns.filter((c) => c.visible).length;
+    const allVisible = visibleCount === columns.length;
+    useEffect(() => {
+        if (!open)
+            return;
+        function handlePointerDown(event) {
+            if (!rootRef.current?.contains(event.target))
+                setOpen(false);
+        }
+        function handleKeyDown(event) {
+            if (event.key === "Escape")
+                setOpen(false);
+        }
+        document.addEventListener("pointerdown", handlePointerDown);
+        document.addEventListener("keydown", handleKeyDown);
+        return () => {
+            document.removeEventListener("pointerdown", handlePointerDown);
+            document.removeEventListener("keydown", handleKeyDown);
+        };
+    }, [open]);
+    function handleDragEnd({ active, over }) {
+        if (!over || active.id === over.id)
+            return;
+        onColumnsChange((prev) => {
+            const oldIndex = prev.findIndex((c) => c.key === active.id);
+            const newIndex = prev.findIndex((c) => c.key === over.id);
+            return arrayMove(prev, oldIndex, newIndex);
+        });
+    }
+    function toggleColumn(key) {
+        onColumnsChange((prev) => prev.map((c) => (c.key === key ? { ...c, visible: !c.visible } : c)));
+    }
+    function reset() {
+        onColumnsChange(() => defaultColumns);
+        setOpen(false);
+    }
+    return (_jsxs("div", { ref: rootRef, "data-slot": "column-menu", className: cn("relative", className?.root), children: [_jsxs("button", { type: "button", "aria-expanded": open, "aria-controls": contentId, onClick: () => {
+                    setOpen((v) => !v);
+                }, className: cn("flex items-center gap-1.5 rounded-lg border px-2.5 py-1.5 text-sm transition-all", open
+                    ? "border-primary bg-primary/10 text-primary"
+                    : "border-border text-foreground/60 hover:border-primary hover:text-foreground", className?.trigger), children: [_jsx("span", { className: "hidden sm:inline", children: text.trigger }), _jsxs("span", { className: cn("rounded-full px-1.5 py-0.5 text-xs font-medium", allVisible
+                            ? "bg-foreground/10 text-foreground/40"
+                            : "bg-primary text-primary-foreground", className?.badge), children: [visibleCount, "/", columns.length] }), _jsx(ChevronDown, { className: cn("size-3.5 opacity-60 transition-transform", open && "rotate-180"), "aria-hidden": "true" })] }), open && (_jsxs("div", { id: contentId, "data-slot": "column-menu-content", className: cn("bg-background border-border absolute top-full z-20 mt-2 w-64 overflow-hidden rounded-xl border shadow-xl", align === "end" ? "right-0" : "left-0", className?.content), children: [_jsxs("div", { className: cn("border-border bg-muted flex items-center justify-between border-b px-4 py-3", className?.header), children: [_jsx("p", { className: "text-foreground text-xs font-medium", children: text.title }), _jsxs("button", { type: "button", onClick: reset, className: "text-foreground/50 hover:text-primary flex items-center gap-1 text-xs transition-colors", children: [_jsx(RotateCcw, { className: "size-3", "aria-hidden": "true" }), text.reset] })] }), _jsx("p", { className: cn("border-border bg-muted/50 text-foreground/50 border-b px-4 py-2 text-xs", className?.hint), children: text.hint }), _jsx("div", { className: cn("p-2", className?.list), children: _jsx(DndContext, { id: dndId, sensors: sensors, collisionDetection: closestCenter, onDragEnd: handleDragEnd, children: _jsx(SortableContext, { items: columns.map((c) => c.key), strategy: verticalListSortingStrategy, children: columns.map((column, index) => (_jsx(SortableColumnRow, { column: column, index: index, total: columns.length, dragHandleLabel: text.dragHandle(column.label), onToggle: toggleColumn, className: className?.row }, column.key))) }) }) })] }))] }));
+}

package/dist/components/column-menu/index.d.ts

@@ -0,0 +1,6 @@
+export type { ColumnMenuProps } from "./column-menu";
+export { ColumnMenu } from "./column-menu";
+export type { ColumnMenuColumn, ColumnMenuLabels } from "./types";
+export { DEFAULT_COLUMN_MENU_LABELS } from "./types";
+export { useDndSensors } from "./use-dnd-sensors";
+//# sourceMappingURL=index.d.ts.map

package/dist/components/column-menu/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/column-menu/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,YAAY,EAAE,gBAAgB,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAClE,OAAO,EAAE,0BAA0B,EAAE,MAAM,SAAS,CAAC;AACrD,OAAO,EAAE,aAAa,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/components/column-menu/index.js

@@ -0,0 +1,3 @@
+export { ColumnMenu } from "./column-menu";
+export { DEFAULT_COLUMN_MENU_LABELS } from "./types";
+export { useDndSensors } from "./use-dnd-sensors";

package/dist/components/column-menu/sortable-column-row.d.ts

@@ -0,0 +1,13 @@
+import type { ColumnMenuColumn } from "./types";
+export interface SortableColumnRowProps<K extends string> {
+    column: ColumnMenuColumn<K>;
+    index: number;
+    total: number;
+    dragHandleLabel: string;
+    onToggle: (key: K) => void;
+    /** Carries `data-dragging` while the row is being dragged. */
+    className?: string;
+}
+/** One row of `ColumnMenu`: drag handle, visibility switch, position. */
+export declare function SortableColumnRow<K extends string>({ column, index, total, dragHandleLabel, onToggle, className, }: SortableColumnRowProps<K>): import("react").JSX.Element;
+//# sourceMappingURL=sortable-column-row.d.ts.map

package/dist/components/column-menu/sortable-column-row.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sortable-column-row.d.ts","sourceRoot":"","sources":["../../../src/components/column-menu/sortable-column-row.tsx"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,SAAS,CAAC;AAEhD,MAAM,WAAW,sBAAsB,CAAC,CAAC,SAAS,MAAM;IACtD,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC,CAAC;IAC5B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,eAAe,EAAE,MAAM,CAAC;IACxB,QAAQ,EAAE,CAAC,GAAG,EAAE,CAAC,KAAK,IAAI,CAAC;IAC3B,8DAA8D;IAC9D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED,yEAAyE;AACzE,wBAAgB,iBAAiB,CAAC,CAAC,SAAS,MAAM,EAAE,EAClD,MAAM,EACN,KAAK,EACL,KAAK,EACL,eAAe,EACf,QAAQ,EACR,SAAS,GACV,EAAE,sBAAsB,CAAC,CAAC,CAAC,+BAuD3B"}

package/dist/components/column-menu/sortable-column-row.js

@@ -0,0 +1,22 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useSortable } from "@dnd-kit/sortable";
+import { CSS } from "@dnd-kit/utilities";
+import { GripVertical } from "lucide-react";
+import { cn } from "@forthtilliath/shadcn-ui/lib/utils";
+import { ToggleSwitch } from "../toggle-switch";
+/** One row of `ColumnMenu`: drag handle, visibility switch, position. */
+export function SortableColumnRow({ column, index, total, dragHandleLabel, onToggle, className, }) {
+    const { attributes, listeners, setNodeRef, transform, transition, isDragging, } = useSortable({ id: column.key });
+    return (_jsxs("div", { ref: setNodeRef, "data-slot": "column-menu-row", "data-dragging": isDragging || undefined, style: {
+            transform: CSS.Transform.toString(transform),
+            transition,
+            opacity: isDragging ? 0.5 : 1,
+            zIndex: isDragging ? 10 : undefined,
+        }, className: cn("flex items-center gap-3 rounded-lg px-3 py-2 transition-colors", isDragging ? "bg-primary/5 border-primary/20 border" : "hover:bg-muted", className), children: [_jsx("button", { type: "button", ...attributes, ...listeners, "aria-label": dragHandleLabel, title: dragHandleLabel, className: "text-foreground/30 hover:text-foreground/60 shrink-0 cursor-grab touch-none transition-colors active:cursor-grabbing", children: _jsx(GripVertical, { className: "size-4", "aria-hidden": "true" }) }), _jsx(ToggleSwitch, { size: "sm", checked: column.visible, onCheckedChange: () => {
+                    onToggle(column.key);
+                }, label: column.label, className: {
+                    root: "flex-1 gap-3",
+                    label: "text-foreground/40 group-data-[state=checked]/toggle-switch:text-foreground flex-1 text-left transition-colors",
+                } }), _jsxs("span", { className: "text-foreground/30 shrink-0 font-mono text-xs", children: [index + 1, "/", total] })] }));
+}

package/dist/components/column-menu/types.d.ts

@@ -0,0 +1,21 @@
+/** A table column the user can show/hide and reorder. */
+export interface ColumnMenuColumn<K extends string = string> {
+    key: K;
+    label: string;
+    visible: boolean;
+}
+/** Texts displayed by `ColumnMenu` (English by default). */
+export interface ColumnMenuLabels {
+    /** Trigger button text (hidden on small screens). */
+    trigger: string;
+    /** Menu title. */
+    title: string;
+    /** Reset button text. */
+    reset: string;
+    /** Usage hint under the title. */
+    hint: string;
+    /** Tooltip / accessible name of a row's drag handle. */
+    dragHandle: (label: string) => string;
+}
+export declare const DEFAULT_COLUMN_MENU_LABELS: ColumnMenuLabels;
+//# sourceMappingURL=types.d.ts.map

package/dist/components/column-menu/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/components/column-menu/types.ts"],"names":[],"mappings":"AAAA,yDAAyD;AACzD,MAAM,WAAW,gBAAgB,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM;IACzD,GAAG,EAAE,CAAC,CAAC;IACP,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;CAClB;AAED,4DAA4D;AAC5D,MAAM,WAAW,gBAAgB;IAC/B,qDAAqD;IACrD,OAAO,EAAE,MAAM,CAAC;IAChB,kBAAkB;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,kCAAkC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,UAAU,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,MAAM,CAAC;CACvC;AAED,eAAO,MAAM,0BAA0B,EAAE,gBAMxC,CAAC"}

package/dist/components/column-menu/types.js

@@ -0,0 +1,7 @@
+export const DEFAULT_COLUMN_MENU_LABELS = {
+    trigger: "Columns",
+    title: "Visible columns",
+    reset: "Reset",
+    hint: "Drag to reorder · toggle to show/hide",
+    dragHandle: (label) => `Move column ${label}`,
+};

package/dist/components/column-menu/use-dnd-sensors.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Mouse (5px threshold, so clicks still work), touch (250ms long press, so
+ * the list still scrolls) and keyboard sensors for a sortable list.
+ */
+export declare function useDndSensors(): import("@dnd-kit/core").SensorDescriptor<import("@dnd-kit/core").SensorOptions>[];
+//# sourceMappingURL=use-dnd-sensors.d.ts.map

package/dist/components/column-menu/use-dnd-sensors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-dnd-sensors.d.ts","sourceRoot":"","sources":["../../../src/components/column-menu/use-dnd-sensors.ts"],"names":[],"mappings":"AAWA;;;GAGG;AACH,wBAAgB,aAAa,sFAU5B"}

package/dist/components/column-menu/use-dnd-sensors.js

@@ -0,0 +1,14 @@
+"use client";
+import { KeyboardSensor, MouseSensor, TouchSensor, useSensor, useSensors, } from "@dnd-kit/core";
+import { sortableKeyboardCoordinates } from "@dnd-kit/sortable";
+/**
+ * Mouse (5px threshold, so clicks still work), touch (250ms long press, so
+ * the list still scrolls) and keyboard sensors for a sortable list.
+ */
+export function useDndSensors() {
+    return useSensors(useSensor(MouseSensor, { activationConstraint: { distance: 5 } }), useSensor(TouchSensor, {
+        activationConstraint: { delay: 250, tolerance: 5 },
+    }), useSensor(KeyboardSensor, {
+        coordinateGetter: sortableKeyboardCoordinates,
+    }));
+}

package/dist/components/command-palette/command-palette.js

@@ -35,7 +35,7 @@ export function CommandPalette({ groups, open, onOpenChange, placeholder = "Type
         return () => {
             document.removeEventListener("keydown", onKeyDown);
         };
-        // eslint-disable-next-line @eslint-react/exhaustive-deps, react-hooks/exhaustive-deps -- `setOpen` is a plain function redefined every render; including it would re-register this listener every render instead of only when `isOpen`/`shortcutKey` actually change, which is what its own re-closure over `isOpen` depends on
+        // eslint-disable-next-line @eslint-react/exhaustive-deps -- `setOpen` is a plain function redefined every render; including it would re-register this listener every render instead of only when `isOpen`/`shortcutKey` actually change, which is what its own re-closure over `isOpen` depends on
     }, [isOpen, shortcutKey]);
     return (_jsxs(CommandDialog, { open: isOpen, onOpenChange: setOpen, title: "Command Palette", description: placeholder, children: [_jsx(CommandInput, { placeholder: placeholder }), _jsxs(CommandList, { children: [_jsx(CommandEmpty, { children: emptyMessage }), groups.map((group, index) => (
                     // eslint-disable-next-line @eslint-react/no-array-index-key -- `heading` is optional and not guaranteed unique

package/dist/components/gradient-frame/gradient-frame.d.ts

@@ -0,0 +1,27 @@
+import type React from "react";
+export interface GradientFrameProps {
+    /** Side the gradient frame sticks out on (default: `"right"`). */
+    side?: "left" | "right";
+    children: React.ReactNode;
+    /**
+     * Custom classes for each part of the component.
+     *
+     * - `root` wraps the frame and the content.
+     * - `frame` is the offset gradient panel — set its colors here with
+     *   gradient stops (`from-* via-* to-*`), the direction (`bg-linear-135`)
+     *   is already set.
+     * - `content` is the rounded, clipped container around `children`.
+     */
+    className?: Partial<Record<"root" | "frame" | "content", string>>;
+}
+/**
+ * A visual (image, video, card…) laid on a rounded frame offset diagonally
+ * behind it, filled with a gradient — a decorative "photo on a colored card"
+ * effect. The offset grows from `md` screens on.
+ *
+ * @version 0.1.0
+ * @author Forth
+ * @copyright 2026 Forth
+ */
+export declare function GradientFrame({ side, children, className, }: GradientFrameProps): React.JSX.Element;
+//# sourceMappingURL=gradient-frame.d.ts.map

package/dist/components/gradient-frame/gradient-frame.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"gradient-frame.d.ts","sourceRoot":"","sources":["../../../src/components/gradient-frame/gradient-frame.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B,MAAM,WAAW,kBAAkB;IACjC,kEAAkE;IAClE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IACxB,QAAQ,EAAE,KAAK,CAAC,SAAS,CAAC;IAC1B;;;;;;;;OAQG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,MAAM,GAAG,OAAO,GAAG,SAAS,EAAE,MAAM,CAAC,CAAC,CAAC;CACnE;AAED;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAAC,EAC5B,IAAc,EACd,QAAQ,EACR,SAAS,GACV,EAAE,kBAAkB,qBAuBpB"}

package/dist/components/gradient-frame/gradient-frame.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@forthtilliath/shadcn-ui/lib/utils";
+/**
+ * A visual (image, video, card…) laid on a rounded frame offset diagonally
+ * behind it, filled with a gradient — a decorative "photo on a colored card"
+ * effect. The offset grows from `md` screens on.
+ *
+ * @version 0.1.0
+ * @author Forth
+ * @copyright 2026 Forth
+ */
+export function GradientFrame({ side = "right", children, className, }) {
+    return (_jsxs("div", { "data-slot": "gradient-frame", className: cn("relative", className?.root), children: [_jsx("div", { "aria-hidden": "true", className: cn("from-primary to-primary/40 absolute inset-0 rounded-3xl bg-linear-135", side === "right"
+                    ? "translate-x-3 translate-y-3 md:translate-x-5 md:translate-y-5"
+                    : "-translate-x-3 translate-y-3 md:-translate-x-5 md:translate-y-5", className?.frame) }), _jsx("div", { className: cn("relative overflow-hidden rounded-3xl shadow-xl", className?.content), children: children })] }));
+}

package/dist/components/gradient-frame/index.d.ts

@@ -0,0 +1,3 @@
+export type { GradientFrameProps } from "./gradient-frame";
+export { GradientFrame } from "./gradient-frame";
+//# sourceMappingURL=index.d.ts.map

package/dist/components/gradient-frame/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/gradient-frame/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/components/gradient-frame/index.js

@@ -0,0 +1 @@
+export { GradientFrame } from "./gradient-frame";

package/dist/components/grid/variants.d.ts

@@ -1,6 +1,6 @@
 import type { VariantProps } from "class-variance-authority";
 export declare const gridVariants: (props?: ({
-    cols?: 1 | 2 | 3 | 7 | 12 | 4 | 5 | 6 | 8 | 9 | 10 | 11 | null | undefined;
+    cols?: 1 | 2 | 3 | 7 | 10 | 5 | 12 | 4 | 6 | 8 | 9 | 11 | null | undefined;
     spacing?: "sm" | "lg" | "none" | "xs" | "md" | "xl" | null | undefined;
 } & import("class-variance-authority/types").ClassProp) | undefined) => string;
 export type GridVariants = VariantProps<typeof gridVariants>;

package/dist/components/icon-bubble/icon-bubble.d.ts

@@ -0,0 +1,21 @@
+import type React from "react";
+import type { IconBubbleVariants } from "./variants";
+export type IconBubbleProps = Omit<React.ComponentProps<"span">, "children"> & IconBubbleVariants & {
+    /** Icon component, e.g. a `lucide-react` icon. Decorative (`aria-hidden`). */
+    icon: React.ComponentType<{
+        size?: number | string;
+        "aria-hidden"?: boolean | "true" | "false";
+    }>;
+};
+/**
+ * An icon inside a round, tinted bubble — e.g. to lead an information line
+ * (date, place…). Tinted with `primary` by default; override both the
+ * background and the icon color through `className`
+ * (`bg-sky-500/15 text-sky-600`).
+ *
+ * @version 0.1.0
+ * @author Forth
+ * @copyright 2026 Forth
+ */
+export declare function IconBubble({ icon: Icon, size, className, ...props }: IconBubbleProps): React.JSX.Element;
+//# sourceMappingURL=icon-bubble.d.ts.map

package/dist/components/icon-bubble/icon-bubble.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"icon-bubble.d.ts","sourceRoot":"","sources":["../../../src/components/icon-bubble/icon-bubble.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC;AAGrD,MAAM,MAAM,eAAe,GAAG,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,MAAM,CAAC,EAAE,UAAU,CAAC,GAC1E,kBAAkB,GAAG;IACnB,8EAA8E;IAC9E,IAAI,EAAE,KAAK,CAAC,aAAa,CAAC;QACxB,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;QACvB,aAAa,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,OAAO,CAAC;KAC5C,CAAC,CAAC;CACJ,CAAC;AAEJ;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,EACzB,IAAI,EAAE,IAAI,EACV,IAAI,EACJ,SAAS,EACT,GAAG,KAAK,EACT,EAAE,eAAe,qBAajB"}

package/dist/components/icon-bubble/icon-bubble.js

@@ -0,0 +1,16 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { cn } from "@forthtilliath/shadcn-ui/lib/utils";
+import { ICON_BUBBLE_ICON_SIZES, iconBubbleVariants } from "./variants";
+/**
+ * An icon inside a round, tinted bubble — e.g. to lead an information line
+ * (date, place…). Tinted with `primary` by default; override both the
+ * background and the icon color through `className`
+ * (`bg-sky-500/15 text-sky-600`).
+ *
+ * @version 0.1.0
+ * @author Forth
+ * @copyright 2026 Forth
+ */
+export function IconBubble({ icon: Icon, size, className, ...props }) {
+    return (_jsx("span", { "data-slot": "icon-bubble", className: cn(iconBubbleVariants({ size }), className), ...props, children: _jsx(Icon, { size: ICON_BUBBLE_ICON_SIZES[size ?? "default"], "aria-hidden": "true" }) }));
+}

package/dist/components/icon-bubble/index.d.ts

@@ -0,0 +1,4 @@
+export type { IconBubbleProps } from "./icon-bubble";
+export { IconBubble } from "./icon-bubble";
+export type { IconBubbleVariants } from "./variants";
+//# sourceMappingURL=index.d.ts.map

package/dist/components/icon-bubble/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/icon-bubble/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,YAAY,EAAE,kBAAkB,EAAE,MAAM,YAAY,CAAC"}

package/dist/components/icon-bubble/index.js

@@ -0,0 +1 @@
+export { IconBubble } from "./icon-bubble";

package/dist/components/icon-bubble/variants.d.ts

@@ -0,0 +1,12 @@
+import type { VariantProps } from "class-variance-authority";
+export declare const iconBubbleVariants: (props?: ({
+    size?: "default" | "sm" | "lg" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+/** Icon size (px) matching each bubble size. */
+export declare const ICON_BUBBLE_ICON_SIZES: {
+    readonly sm: 14;
+    readonly default: 17;
+    readonly lg: 20;
+};
+export type IconBubbleVariants = VariantProps<typeof iconBubbleVariants>;
+//# sourceMappingURL=variants.d.ts.map

package/dist/components/icon-bubble/variants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"variants.d.ts","sourceRoot":"","sources":["../../../src/components/icon-bubble/variants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAG7D,eAAO,MAAM,kBAAkB;;8EAc9B,CAAC;AAEF,gDAAgD;AAChD,eAAO,MAAM,sBAAsB;;;;CAIzB,CAAC;AAEX,MAAM,MAAM,kBAAkB,GAAG,YAAY,CAAC,OAAO,kBAAkB,CAAC,CAAC"}

package/dist/components/icon-bubble/variants.js

@@ -0,0 +1,19 @@
+import { cva } from "class-variance-authority";
+export const iconBubbleVariants = cva("bg-primary/15 text-primary grid shrink-0 place-items-center rounded-full", {
+    variants: {
+        size: {
+            sm: "size-7",
+            default: "size-9",
+            lg: "size-11",
+        },
+    },
+    defaultVariants: {
+        size: "default",
+    },
+});
+/** Icon size (px) matching each bubble size. */
+export const ICON_BUBBLE_ICON_SIZES = {
+    sm: 14,
+    default: 17,
+    lg: 20,
+};

package/dist/components/image-input/image-input.js

@@ -18,7 +18,7 @@ export function ImageInput({ value, onFileChange, disabled = false, className, a
     const inputRef = React.useRef(null);
     React.useEffect(() => {
         if (file === null) {
-            // eslint-disable-next-line @eslint-react/set-state-in-effect, react-hooks/set-state-in-effect -- syncs the object URL lifecycle (create/revoke) with the selected File, an external browser resource that can't be derived during render
+            // eslint-disable-next-line @eslint-react/set-state-in-effect -- syncs the object URL lifecycle (create/revoke) with the selected File, an external browser resource that can't be derived during render
             setObjectUrl(null);
             return;
         }

package/dist/components/relative-time/relative-time.js

@@ -39,7 +39,7 @@ export function RelativeTime({ date, timeZone, label, formatOptions, className,
         // ones — there's no way to read "now" during render without
         // reintroducing the hydration mismatch this state is starting
         // `undefined` to avoid.
-        // eslint-disable-next-line @eslint-react/set-state-in-effect, react-hooks/set-state-in-effect
+        // eslint-disable-next-line @eslint-react/set-state-in-effect
         setLiveNow(new Date());
         const interval = setInterval(() => {
             setLiveNow(new Date());

package/dist/components/toggle-switch/index.d.ts

@@ -0,0 +1,4 @@
+export type { ToggleSwitchProps } from "./toggle-switch";
+export { ToggleSwitch } from "./toggle-switch";
+export type { ToggleSwitchSizeVariants } from "./variants";
+//# sourceMappingURL=index.d.ts.map

package/dist/components/toggle-switch/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/components/toggle-switch/index.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,iBAAiB,EAAE,MAAM,iBAAiB,CAAC;AACzD,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,YAAY,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC"}

package/dist/components/toggle-switch/index.js

@@ -0,0 +1 @@
+export { ToggleSwitch } from "./toggle-switch";

package/dist/components/toggle-switch/toggle-switch.d.ts

@@ -0,0 +1,37 @@
+import type React from "react";
+import type { ToggleSwitchSizeVariants } from "./variants";
+export type ToggleSwitchProps = Omit<React.ComponentProps<"button">, "children" | "className" | "onChange" | "onClick" | "role" | "type" | "value"> & ToggleSwitchSizeVariants & {
+    checked: boolean;
+    onCheckedChange: (checked: boolean) => void;
+    /** Visible text, also used as the accessible name. */
+    label?: React.ReactNode;
+    /** Secondary text under the label. */
+    description?: React.ReactNode;
+    /** Side of the text relative to the track (default: `"end"`). */
+    labelPosition?: "start" | "end";
+    /**
+     * Custom classes for each part of the component.
+     *
+     * - `root` is the `<button role="switch">` element — a `group/toggle-switch`
+     *   carrying `data-state="checked" | "unchecked"`, so any part can be
+     *   styled per state (`group-data-[state=checked]/toggle-switch:...`).
+     * - `track` / `thumb` are the switch itself.
+     * - `text` wraps the label and description (only when a description is set).
+     * - `label` / `description` are the text elements.
+     */
+    className?: Partial<Record<"root" | "track" | "thumb" | "text" | "label" | "description", string>>;
+};
+/**
+ * An on/off switch (`role="switch"`) with an optional visible label and
+ * description — clicking the text toggles it too. Visually distinct from an
+ * action button.
+ *
+ * Unlike shadcn's `Switch`, it has no Radix dependency and bundles the label,
+ * so a whole settings row is a single, fully clickable element.
+ *
+ * @version 0.1.0
+ * @author Forth
+ * @copyright 2026 Forth
+ */
+export declare function ToggleSwitch({ checked, onCheckedChange, label, description, labelPosition, size, className, ...props }: ToggleSwitchProps): React.JSX.Element;
+//# sourceMappingURL=toggle-switch.d.ts.map

package/dist/components/toggle-switch/toggle-switch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toggle-switch.d.ts","sourceRoot":"","sources":["../../../src/components/toggle-switch/toggle-switch.tsx"],"names":[],"mappings":"AAEA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAI/B,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,YAAY,CAAC;AAM3D,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAClC,KAAK,CAAC,cAAc,CAAC,QAAQ,CAAC,EAC9B,UAAU,GAAG,WAAW,GAAG,UAAU,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAC9E,GACC,wBAAwB,GAAG;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,eAAe,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;IAC5C,sDAAsD;IACtD,KAAK,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IACxB,sCAAsC;IACtC,WAAW,CAAC,EAAE,KAAK,CAAC,SAAS,CAAC;IAC9B,iEAAiE;IACjE,aAAa,CAAC,EAAE,OAAO,GAAG,KAAK,CAAC;IAChC;;;;;;;;;OASG;IACH,SAAS,CAAC,EAAE,OAAO,CACjB,MAAM,CACJ,MAAM,GAAG,OAAO,GAAG,OAAO,GAAG,MAAM,GAAG,OAAO,GAAG,aAAa,EAC7D,MAAM,CACP,CACF,CAAC;CACH,CAAC;AAEJ;;;;;;;;;;;GAWG;AACH,wBAAgB,YAAY,CAAC,EAC3B,OAAO,EACP,eAAe,EACf,KAAK,EACL,WAAW,EACX,aAAqB,EACrB,IAAI,EACJ,SAAS,EACT,GAAG,KAAK,EACT,EAAE,iBAAiB,qBAmDnB"}

package/dist/components/toggle-switch/toggle-switch.js

@@ -0,0 +1,25 @@
+"use client";
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "@forthtilliath/shadcn-ui/lib/utils";
+import { toggleSwitchThumbVariants, toggleSwitchTrackVariants, } from "./variants";
+/**
+ * An on/off switch (`role="switch"`) with an optional visible label and
+ * description — clicking the text toggles it too. Visually distinct from an
+ * action button.
+ *
+ * Unlike shadcn's `Switch`, it has no Radix dependency and bundles the label,
+ * so a whole settings row is a single, fully clickable element.
+ *
+ * @version 0.1.0
+ * @author Forth
+ * @copyright 2026 Forth
+ */
+export function ToggleSwitch({ checked, onCheckedChange, label, description, labelPosition = "end", size, className, ...props }) {
+    const labelNode = label === undefined ? null : (_jsx("span", { className: cn("text-foreground text-sm", className?.label), children: label }));
+    // Without a description, the label is a direct flex child so that hiding it
+    // (e.g. `hidden sm:inline`) also removes the gap.
+    const text = description === undefined ? (labelNode) : (_jsxs("span", { className: cn("flex flex-col text-left", className?.text), children: [labelNode, _jsx("span", { className: cn("text-foreground/60 text-xs", className?.description), children: description })] }));
+    return (_jsxs("button", { type: "button", role: "switch", "aria-checked": checked, "data-slot": "toggle-switch", "data-state": checked ? "checked" : "unchecked", onClick: () => {
+            onCheckedChange(!checked);
+        }, className: cn("group/toggle-switch inline-flex cursor-pointer items-center gap-2 rounded-md focus-visible:outline-none disabled:cursor-not-allowed disabled:opacity-50", className?.root), ...props, children: [labelPosition === "start" && text, _jsx("span", { "data-slot": "toggle-switch-track", className: cn(toggleSwitchTrackVariants({ size }), className?.track), children: _jsx("span", { className: cn(toggleSwitchThumbVariants({ size }), className?.thumb) }) }), labelPosition === "end" && text] }));
+}

package/dist/components/toggle-switch/variants.d.ts

@@ -0,0 +1,9 @@
+import type { VariantProps } from "class-variance-authority";
+export declare const toggleSwitchTrackVariants: (props?: ({
+    size?: "default" | "sm" | "lg" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export declare const toggleSwitchThumbVariants: (props?: ({
+    size?: "default" | "sm" | "lg" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export type ToggleSwitchSizeVariants = VariantProps<typeof toggleSwitchTrackVariants>;
+//# sourceMappingURL=variants.d.ts.map

package/dist/components/toggle-switch/variants.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"variants.d.ts","sourceRoot":"","sources":["../../../src/components/toggle-switch/variants.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAG7D,eAAO,MAAM,yBAAyB;;8EAmBrC,CAAC;AAEF,eAAO,MAAM,yBAAyB;;8EAerC,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG,YAAY,CACjD,OAAO,yBAAyB,CACjC,CAAC"}