fancy-ui-svelte 0.4.1 → 0.6.0

package/README.md

@@ -5,7 +5,7 @@ Beautiful animation and UI components for **Svelte 5**.
 ![Svelte 5](https://img.shields.io/badge/Svelte-5-FF3E00?logo=svelte&logoColor=white)
 ![Tailwind CSS](https://img.shields.io/badge/Tailwind_CSS-4-06B6D4?logo=tailwindcss&logoColor=white)
 ![TypeScript](https://img.shields.io/badge/TypeScript-5-3178C6?logo=typescript&logoColor=white)
-![Components](https://img.shields.io/badge/Components-52-8B5CF6)
+![Components](https://img.shields.io/badge/Components-56-8B5CF6)
 ![MIT License](https://img.shields.io/badge/License-MIT-green)
 
 <p align="center">
@@ -23,7 +23,7 @@ Beautiful animation and UI components for **Svelte 5**.
 - **Svelte 5 Runes** &mdash; Built with `$state`, `$derived`, `$effect`, and `$props`
 - **Tailwind CSS 4** &mdash; Utility-first styling with theme tokens
 - **TypeScript** &mdash; Fully typed props and events
-- **52 Components** &mdash; Buttons, text animations, backgrounds, effects, and more
+- **56 Components** &mdash; Buttons, text animations, backgrounds, effects, and more
 - **Dark Mode** &mdash; All components support light and dark themes
 - **Tested** &mdash; Component tests with Vitest and Testing Library
 
@@ -119,21 +119,35 @@ Beautiful animation and UI components for **Svelte 5**.
 **Install via npm:**
 
 ```bash
-npm install fancy-ui
+npm install fancy-ui-svelte
 ```
 
 Then import any component:
 
 ```ts
-import { Marquee, BorderBeam, Confetti } from 'fancy-ui';
+import { Marquee, BorderBeam, Confetti } from 'fancy-ui-svelte';
 ```
 
-To include Tailwind classes, add this to your app's CSS:
+Add the Tailwind integration to your app's CSS (e.g. `src/app.css`):
 
 ```css
-@import "fancy-ui/tailwind.css";
+@import "tailwindcss";
+@import "fancy-ui-svelte/tailwind.css";
 ```
 
+This single import tells Tailwind v4 to scan the library's components so all utility classes are generated automatically. No manual `@source` path needed.
+
+<details>
+<summary>Alternative: manual @source (without the CSS import)</summary>
+
+```css
+@import "tailwindcss";
+@source "../node_modules/fancy-ui-svelte/dist";
+```
+
+The path is relative to your CSS file location.
+</details>
+
 **Or browse and copy a component:**
 1. Find the component you need in the [live demo](https://fancy-ui.rama.app)
 2. Copy the source from `src/lib/fancy-ui/[component-name]/`
@@ -148,6 +162,25 @@ pnpm install
 pnpm dev
 ```
 
+## Using with AI agents (Claude Code, Cursor, Copilot)
+
+The docs site serves LLM-friendly documentation following the [llms.txt](https://llmstxt.org) convention:
+
+- [fancy-ui.rama.app/llms.txt](https://fancy-ui.rama.app/llms.txt) — setup guide, usage rules, and component index
+- [fancy-ui.rama.app/llms-full.txt](https://fancy-ui.rama.app/llms-full.txt) — full reference with every component's props
+
+To make your coding agent use fancy-ui correctly, add this to your project's `CLAUDE.md`, `AGENTS.md`, or `.cursorrules`:
+
+```markdown
+## UI components
+
+Use fancy-ui-svelte (Svelte 5 + Tailwind CSS v4) for animated UI components.
+Full component and props reference: https://fancy-ui.rama.app/llms-full.txt
+Key rules: overlay/effect components (BorderBeam, GlowBorder, backgrounds, ...)
+need a parent with `relative overflow-hidden`; cursor effects (FluidCursor,
+SmoothCursor) mount once in the root +layout.svelte; Svelte 5 syntax only.
+```
+
 ## Development
 
 ```bash
@@ -181,7 +214,7 @@ src/
 
 ## Contributing
 
-Contributions are welcome! 52 components and counting — PRs for new components, bug fixes, and improvements are appreciated.
+Contributions are welcome! 56 components and counting — PRs for new components, bug fixes, and improvements are appreciated.
 
 ### Adding a new component
 

package/dist/fancy-ui/dock/index.d.ts

@@ -1,4 +1,4 @@
 export { default as Dock } from "./Dock.svelte";
 export { default as DockIcon } from "./DockIcon.svelte";
 export { default as DockSeparator } from "./DockSeparator.svelte";
-export * from "./types";
+export type { DataOrientation, Direction, DockContext } from "./types.js";

package/dist/fancy-ui/dock/index.js

@@ -1,4 +1,3 @@
 export { default as Dock } from "./Dock.svelte";
 export { default as DockIcon } from "./DockIcon.svelte";
 export { default as DockSeparator } from "./DockSeparator.svelte";
-export * from "./types";

package/dist/fancy-ui/editorial-engine/EditorialEngine.svelte

@@ -0,0 +1,181 @@
+<script lang="ts" module>
+	/**
+	 * Props for EditorialEngine
+	 *
+	 * Live magazine layout: multi-column text flow with cursor handoff,
+	 * auto-fitted headline, drop cap, pullquotes, and body text reflowing in
+	 * real time around draggable animated orbs. All line breaking is computed
+	 * by @chenglou/pretext — the render loop performs zero DOM reads.
+	 *
+	 * Inspired by the pretext "editorial engine" demo
+	 * (https://chenglou.me/pretext/editorial-engine/).
+	 */
+	export interface EditorialEngineProps {
+		/** Headline, auto-sized to the widest font that breaks no word */
+		headline?: string;
+		/** Body copy (plain text, paragraphs separated by blank lines) */
+		body?: string;
+		/** Up to two pullquotes embedded in the columns */
+		pullquotes?: string[];
+		/** Font family stack used for all text */
+		fontFamily?: string;
+		/** Additional CSS classes for the stage */
+		class?: string;
+	}
+</script>
+
+<script lang="ts">
+	import { cn } from "../../utils.js";
+	import { createEditorialEngine } from "./engine.js";
+
+	const DEFAULT_HEADLINE = "TEXT THAT FLOWS AROUND ANYTHING";
+
+	const DEFAULT_BODY = `Print designers have flowed text around images, illustrations, and odd-shaped figures for more than a century. The web never caught up. CSS gives us float, and more recently shape-outside, but both only push text away from one side of one static box. Flowing text through multiple columns, around several moving obstacles at once, filling the gaps on both sides — the browser has no answer for that.
+
+The reason is not a lack of imagination. It is the cost of asking. Every question about text — how wide is this word, where does this line break, how tall is this paragraph — must go through the browser's layout engine, and the layout engine answers by reflowing the document. Ask too often and the interface stutters. So we learned not to ask, and our text stayed in rigid rectangles.
+
+This page asks hundreds of times per frame. Every line of text you are reading was positioned by arithmetic, not by the browser. The pretext library measured every word once, up front, against a canvas font engine. After that, layout is pure math: given a width, it returns line breaks, line widths, and a cursor pointing at exactly where the text stopped.
+
+That cursor is what makes columns work. The first column consumes text until it runs out of vertical space, then hands its cursor to the second column, which continues mid-sentence without duplication or gaps. Newspapers have done this on paper forever; on the web it has always required hidden elements and fragile content splitting.
+
+The orbs drifting across the page are obstacles, not decoration. Each frame, the engine intersects every text line's vertical band with every orb, subtracts the blocked intervals from the column width, and fills every remaining slot — text flows on both sides of an orb at once, something shape-outside cannot express at all.
+
+Drag an orb and the paragraphs part around it in real time. Click one and it pauses. Resize the window and the headline re-fits itself, searching for the largest font size that breaks no word across lines — a binary search that costs microseconds because each probe is arithmetic, not reflow.
+
+The drop cap at the top of this article is another obstacle: a rectangle carved out of the first column's first three lines. The pullquotes are the same trick at a larger scale. Everything you see is one mechanism — carve the blocked intervals out of each line's band, lay out text in whatever space remains.
+
+When the engine finishes a frame, it writes positions and text content to a pool of absolutely positioned elements, and nothing else. The browser never computes layout for this page's body text, because every coordinate is already known. A full reflow of every line around five moving obstacles typically costs a fraction of a millisecond.
+
+Cheap text measurement changes what interfaces can be. Virtualized lists can know every item's exact height before rendering it. Chat bubbles can shrink-wrap to their tightest width. Labels can dodge chart elements as you zoom. Documents can flow around widgets that other people are dragging in real time.
+
+None of this needs a new browser API or a standards process. It needs cached font metrics, a line breaker, and the willingness to stop asking the DOM questions it answers slowly. The text on this page stopped asking. And so it flows.`;
+
+	const DEFAULT_PULLQUOTES = [
+		"“Text flows on both sides of a moving obstacle at once — something shape-outside cannot express at all.”",
+		"“Every coordinate is already known. The browser never computes layout for this text.”",
+	];
+
+	const DEFAULT_FONT_FAMILY =
+		'"Iowan Old Style", "Palatino Linotype", "Book Antiqua", Palatino, serif';
+
+	let {
+		headline = DEFAULT_HEADLINE,
+		body = DEFAULT_BODY,
+		pullquotes = DEFAULT_PULLQUOTES,
+		fontFamily = DEFAULT_FONT_FAMILY,
+		class: className,
+	}: EditorialEngineProps = $props();
+
+	let stageRef: HTMLDivElement;
+	let ready = $state(false);
+
+	// Re-created whenever the text props change, so the prepared measurements
+	// always match the rendered content. Effects never run during SSR.
+	$effect(() => {
+		const options = { headline, body, pullquotes, fontFamily };
+		let destroy: (() => void) | null = null;
+		let cancelled = false;
+
+		// pretext measures against the canvas font engine — fonts must be
+		// loaded first or widths come from the fallback font.
+		document.fonts.ready.then(() => {
+			if (cancelled) return;
+			destroy = createEditorialEngine(stageRef, options);
+			ready = true;
+		});
+
+		return () => {
+			cancelled = true;
+			destroy?.();
+		};
+	});
+</script>
+
+<div
+	bind:this={stageRef}
+	class={cn("ee-stage", className)}
+	style:font-family={fontFamily}
+	class:ready
+>
+	{#if !ready}
+		<!-- SSR / pre-engine fallback: keeps the content in the HTML -->
+		<div class="ee-fallback" aria-hidden="false">
+			<h2>{headline}</h2>
+			<p>{body}</p>
+		</div>
+	{/if}
+</div>
+
+<style>
+	.ee-stage {
+		position: relative;
+		width: 100%;
+		height: 100%;
+		overflow: hidden;
+		background: radial-gradient(ellipse at 50% 40%, #0f0f14 0%, #0a0a0c 100%);
+		color: #e8e4dc;
+		touch-action: none;
+	}
+
+	.ee-fallback {
+		position: absolute;
+		inset: 0;
+		padding: 48px;
+		overflow: hidden;
+		opacity: 0.4;
+		font-size: 14px;
+	}
+
+	.ee-stage :global(.ee-line) {
+		position: absolute;
+		white-space: pre;
+		z-index: 1;
+		color: #e8e4dc;
+		user-select: text;
+		-webkit-user-select: text;
+	}
+
+	.ee-stage :global(.ee-headline-line) {
+		position: absolute;
+		white-space: pre;
+		font-weight: 700;
+		color: #fff;
+		letter-spacing: -0.5px;
+		z-index: 2;
+		user-select: text;
+		-webkit-user-select: text;
+	}
+
+	.ee-stage :global(.ee-drop-cap) {
+		position: absolute;
+		pointer-events: none;
+		z-index: 2;
+		font-weight: 700;
+		color: #c4a35a;
+	}
+
+	.ee-stage :global(.ee-orb) {
+		position: absolute;
+		border-radius: 50%;
+		pointer-events: none;
+		z-index: 10;
+		will-change: transform;
+	}
+
+	.ee-stage :global(.ee-pullquote-box) {
+		position: absolute;
+		pointer-events: none;
+		z-index: 3;
+		border-left: 3px solid #6b5a3d;
+		padding-left: 14px;
+	}
+
+	.ee-stage :global(.ee-pullquote-line) {
+		position: absolute;
+		white-space: pre;
+		font-style: italic;
+		color: #b8a070;
+		user-select: text;
+		-webkit-user-select: text;
+	}
+</style>

package/dist/fancy-ui/editorial-engine/EditorialEngine.svelte.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Props for EditorialEngine
+ *
+ * Live magazine layout: multi-column text flow with cursor handoff,
+ * auto-fitted headline, drop cap, pullquotes, and body text reflowing in
+ * real time around draggable animated orbs. All line breaking is computed
+ * by @chenglou/pretext — the render loop performs zero DOM reads.
+ *
+ * Inspired by the pretext "editorial engine" demo
+ * (https://chenglou.me/pretext/editorial-engine/).
+ */
+export interface EditorialEngineProps {
+    /** Headline, auto-sized to the widest font that breaks no word */
+    headline?: string;
+    /** Body copy (plain text, paragraphs separated by blank lines) */
+    body?: string;
+    /** Up to two pullquotes embedded in the columns */
+    pullquotes?: string[];
+    /** Font family stack used for all text */
+    fontFamily?: string;
+    /** Additional CSS classes for the stage */
+    class?: string;
+}
+declare const EditorialEngine: import("svelte").Component<EditorialEngineProps, {}, "">;
+type EditorialEngine = ReturnType<typeof EditorialEngine>;
+export default EditorialEngine;

package/dist/fancy-ui/editorial-engine/README.md

@@ -0,0 +1,56 @@
+# EditorialEngine
+
+Live magazine layout powered by [@chenglou/pretext](https://github.com/chenglou/pretext):
+multi-column text flow with cursor handoff, auto-fitted headline, drop cap,
+pullquotes, and body text reflowing in real time around draggable animated
+orbs. The render loop performs **zero DOM reads** — every line position is
+computed arithmetically from cached font metrics, and the only DOM operations
+are writes (`left`, `top`, `textContent`).
+
+Inspired by the pretext
+[editorial engine demo](https://chenglou.me/pretext/editorial-engine/).
+
+## How it works
+
+- `prepareWithSegments(body, font)` measures the text once against the canvas
+  font engine.
+- Each frame, every text line's vertical band is intersected with each orb;
+  blocked horizontal intervals are subtracted from the column width and
+  `layoutNextLine` fills every remaining slot — text flows on **both sides**
+  of an obstacle, which CSS `shape-outside` cannot do.
+- Columns hand a `LayoutCursor` to one another, so text continues
+  mid-sentence across column boundaries like print.
+- The headline binary-searches the largest font size that breaks no word
+  (`walkLineRanges` to detect intra-word breaks).
+
+## Usage
+
+```svelte
+<script lang="ts">
+	import { EditorialEngine } from "$lib/fancy-ui/editorial-engine";
+</script>
+
+<div class="h-[85vh]">
+	<EditorialEngine />
+</div>
+```
+
+The stage fills its parent — give the parent an explicit height.
+
+## Props
+
+| Prop         | Type       | Default              | Description                                       |
+| ------------ | ---------- | -------------------- | ------------------------------------------------- |
+| `headline`   | `string`   | built-in copy        | Auto-sized headline (largest size, no word break) |
+| `body`       | `string`   | built-in copy        | Body text, paragraphs separated by blank lines    |
+| `pullquotes` | `string[]` | built-in quotes      | Up to two pullquotes embedded in the columns      |
+| `fontFamily` | `string`   | Palatino serif stack | Font stack for all text                           |
+| `class`      | `string`   | —                    | Additional CSS classes for the stage              |
+
+## Interactions
+
+- **Drag** an orb — text reparts around it every frame.
+- **Click** an orb — pauses/resumes its drift.
+- **Resize** — headline re-fits, column count adapts (1/2/3), text reflows.
+- Text stays selectable; rendering pauses while a selection is active.
+- `prefers-reduced-motion` starts all orbs paused (still draggable).

package/dist/fancy-ui/editorial-engine/engine.d.ts

@@ -0,0 +1,7 @@
+export interface EditorialEngineOptions {
+    headline: string;
+    body: string;
+    pullquotes: string[];
+    fontFamily: string;
+}
+export declare function createEditorialEngine(stage: HTMLDivElement, options: EditorialEngineOptions): () => void;