kumo-svelte 0.1.0-beta.0

package/src/routes/components/tabs/+page.md

@@ -0,0 +1,156 @@
+---
+title: "Tabs"
+description: "A set of layered sections of content, known as tab panels, displayed one at a time."
+sourceFile: "components/tabs"
+bitsUIComponent: "tabs"
+---
+
+<script>
+  import ComponentExample from '$lib/docs/ComponentExample.svelte';
+  import ComponentSection from '$lib/docs/ComponentSection.svelte';
+  import PropsTable from '$lib/docs/PropsTable.svelte';
+</script>
+
+<!-- Hero Demo -->
+
+<ComponentSection>
+  <ComponentExample demo="TabsDefaultDemo" />
+</ComponentSection>
+
+<!-- Installation -->
+
+<ComponentSection>
+
+## Installation
+
+### Barrel
+
+```svelte
+import { Tabs } from "kumo-svelte";
+```
+
+### Granular
+
+```svelte
+import { Tabs } from "kumo-svelte";
+```
+
+</ComponentSection>
+
+<!-- Usage -->
+
+<ComponentSection>
+
+## Usage
+
+```svelte
+import { Tabs } from "kumo-svelte";
+
+<Tabs
+  tabs={[
+    { value: "overview", label: "Overview" },
+    { value: "settings", label: "Settings" },
+  ]}
+  selectedValue="overview"
+/>
+```
+
+</ComponentSection>
+
+<!-- Examples -->
+
+<ComponentSection>
+
+## Examples
+
+### Variants
+
+#### Segmented (Default)
+
+A pill-shaped indicator slides between tabs on a subtle background.
+
+<ComponentExample demo="TabsSegmentedDemo" />
+
+#### Underline
+
+A bottom border with a primary-colored indicator. The active tab has bolder
+text for emphasis.
+
+<ComponentExample demo="TabsUnderlineDemo" />
+
+### Small Size
+
+Use `size="sm"` for a compact tab bar that matches `Input size="sm"` height (h-6.5 / 26px).
+Useful inside toolbars and filter rows.
+
+<ComponentExample demo="TabsSmDemo" />
+
+### Controlled
+
+Use the `value` and `onValueChange` props for controlled state.
+
+<ComponentExample demo="TabsControlledDemo" />
+
+### Many Tabs
+
+Tabs automatically scroll horizontally when there are many items.
+
+<ComponentExample demo="TabsManyDemo" />
+
+</ComponentSection>
+
+<!-- API Reference -->
+
+<ComponentSection>
+
+## API Reference
+
+  <PropsTable component="Tabs" />
+
+### TabsItem
+
+<div class="overflow-x-auto">
+  <table class="w-full text-sm">
+    <thead>
+      <tr class="border-b border-kumo-hairline">
+        <th class="px-4 py-3 text-left font-semibold">Property</th>
+        <th class="px-4 py-3 text-left font-semibold">Type</th>
+        <th class="px-4 py-3 text-left font-semibold">Required</th>
+      </tr>
+    </thead>
+    <tbody class="text-kumo-subtle">
+      <tr class="border-b border-kumo-hairline">
+        <td class="px-4 py-3 font-mono text-xs">value</td>
+        <td class="px-4 py-3 font-mono text-xs">string</td>
+        <td class="px-4 py-3 font-mono text-xs">Yes</td>
+      </tr>
+      <tr class="border-b border-kumo-hairline">
+        <td class="px-4 py-3 font-mono text-xs">label</td>
+        <td class="px-4 py-3 font-mono text-xs">string | Snippet</td>
+        <td class="px-4 py-3 font-mono text-xs">Yes</td>
+      </tr>
+      <tr class="border-b border-kumo-hairline">
+        <td class="px-4 py-3 font-mono text-xs">disabled</td>
+        <td class="px-4 py-3 font-mono text-xs">boolean</td>
+        <td class="px-4 py-3 font-mono text-xs">No</td>
+      </tr>
+      <tr class="border-b border-kumo-hairline">
+        <td class="px-4 py-3 font-mono text-xs">class</td>
+        <td class="px-4 py-3 font-mono text-xs">string</td>
+        <td class="px-4 py-3 font-mono text-xs">No</td>
+      </tr>
+      <tr class="border-b border-kumo-hairline">
+        <td class="px-4 py-3 font-mono text-xs">className</td>
+        <td class="px-4 py-3 font-mono text-xs">string</td>
+        <td class="px-4 py-3 font-mono text-xs">No</td>
+      </tr>
+      <tr class="border-b border-kumo-hairline">
+        <td class="px-4 py-3 font-mono text-xs">content</td>
+        <td class="px-4 py-3 font-mono text-xs">Snippet</td>
+        <td class="px-4 py-3 font-mono text-xs">No</td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+
+</ComponentSection>

package/src/routes/components/text/+page.md

@@ -0,0 +1,134 @@
+---
+title: "Text"
+description: "A typography component for various heading and copy styles."
+sourceFile: "components/text"
+---
+
+<script>
+  import ComponentExample from '$lib/docs/ComponentExample.svelte';
+  import ComponentSection from '$lib/docs/ComponentSection.svelte';
+  import PropsTable from '$lib/docs/PropsTable.svelte';
+</script>
+
+<!-- Hero Demo -->
+
+<ComponentSection>
+  <ComponentExample demo="TextVariantsDemo" />
+</ComponentSection>
+
+<!-- Installation -->
+
+<ComponentSection>
+
+## Installation
+
+### Barrel
+
+```svelte
+<script lang="ts">
+  import { Text } from 'kumo-svelte';
+</script>
+```
+
+### Granular
+
+```svelte
+<script lang="ts">
+  import { Text } from 'kumo-svelte';
+</script>
+```
+
+</ComponentSection>
+
+<!-- Usage -->
+
+<ComponentSection>
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { Text } from 'kumo-svelte';
+</script>
+
+<Text>Your content here</Text>
+```
+
+### Semantic HTML
+
+The `variant` prop controls visual styling only - it does not determine the HTML element rendered. Heading variants **require** the `as` prop to avoid silently excluding real section headings from the document outline. Body and monospace variants have sensible defaults (`<p>` and `<span>` respectively) and accept `as` optionally.
+
+```svelte
+<!-- Heading variants REQUIRE `as` — TypeScript will flag usages missing it -->
+<Text variant="heading1">Page Title</Text> <!-- Doesn't compile -->
+
+<!-- Real section headings (contribute to the document outline) -->
+<Text variant="heading1" as="h1">Page Title</Text>
+<Text variant="heading2" as="h2">Section Title</Text>
+
+<!-- Decorative heading-styled text that is NOT a section heading -->
+<Text variant="heading1" as="span">Big bold card label</Text>
+
+<!-- Visually one size, semantically another -->
+<Text variant="heading1" as="h3">Visually large, but semantically h3</Text>
+```
+
+
+The `as` prop accepts: `"h1"` through `"h6"`, `"p"`, and `"span"`. Body variants default to `"p"`, monospace variants default to `"span"`, and heading variants have no default - you must choose explicitly.
+
+### Restrictions
+
+The `bold` and `size` props are intentionally restricted to the `base`, `secondary`, `success`, and `error` text variants.
+
+```svelte
+<Text size="sm" bold>Body</Text>
+<Text variant="secondary" bold>Body secondary</Text>
+<Text variant="success" size="lg">Success</Text>
+<Text variant="error">Error</Text>
+```
+
+
+Monospace variants (`mono` and `mono-secondary`) can only set `size` to `lg` and cannot use the `bold` prop:
+
+```svelte
+<Text variant="mono">Monospace</Text>
+<Text variant="mono" size="lg">Monospace</Text>
+<Text variant="mono" bold>Monospace</Text> // Doesn't compile
+```
+
+
+Headings (i.e. `heading1`, `heading2` and `heading3` variants) cannot use these props at all:
+
+```svelte
+<Text variant="heading1" bold>
+  Heading 1
+</Text> // Doesn't compile
+```
+
+</ComponentSection>
+
+<!-- Truncate -->
+
+<ComponentSection>
+
+## Truncate
+
+
+<p>Use the `truncate` prop to clip overflowing text with an ellipsis. This adds `truncate min-w-0` classes, which is useful when `Text` is inside a flex or grid container.</p>
+
+<ComponentExample demo="TextTruncateDemo" />
+
+```svelte
+<Text truncate>This is a long piece of text that will be truncated...</Text>
+```
+
+</ComponentSection>
+
+<!-- API Reference -->
+
+<ComponentSection>
+
+## API Reference
+
+  <PropsTable component="Text" />
+</ComponentSection>

package/src/routes/components/toast/+page.md

@@ -0,0 +1,290 @@
+---
+title: "Toast"
+description: "A notification system for displaying brief, non-intrusive messages to users."
+sourceFile: "components/toast"
+---
+
+<script>
+  import ComponentExample from '$lib/docs/ComponentExample.svelte';
+  import ComponentSection from '$lib/docs/ComponentSection.svelte';
+  import PropsTable from '$lib/docs/PropsTable.svelte';
+</script>
+
+<!-- Hero Demo -->
+
+<ComponentSection>
+  <ComponentExample demo="ToastBasicDemo" />
+</ComponentSection>
+
+<!-- Installation -->
+
+<ComponentSection>
+
+## Installation
+
+### Barrel
+
+```svelte
+<script lang="ts">
+  import { Toasty, useKumoToastManager } from 'kumo-svelte';
+</script>
+```
+
+### Granular
+
+```svelte
+<script lang="ts">
+  import { Toasty, useKumoToastManager } from 'kumo-svelte';
+</script>
+```
+
+</ComponentSection>
+
+<!-- Usage -->
+
+<ComponentSection>
+
+## Usage
+
+The toast system consists of two parts: the `Toasty` provider component and the `useKumoToastManager()` hook for triggering toasts.
+
+```svelte
+<!-- ToastTrigger.svelte -->
+<script lang="ts">
+  import { Button, useKumoToastManager } from 'kumo-svelte';
+
+  const toastManager = useKumoToastManager();
+</script>
+
+<Button
+  onclick={() =>
+    toastManager.add({
+      title: 'Success!',
+      description: 'Your changes have been saved.'
+    })}
+>
+  Save changes
+</Button>
+```
+
+```svelte
+<!-- +layout.svelte -->
+<script lang="ts">
+  import { Toasty } from 'kumo-svelte';
+  import ToastTrigger from './ToastTrigger.svelte';
+</script>
+
+<Toasty>
+  <ToastTrigger />
+</Toasty>
+```
+
+</ComponentSection>
+
+<!-- Setup -->
+
+<ComponentSection>
+
+## Setup
+
+  
+Wrap your application (or a section of it) with the `Toasty` provider. This sets up the toast context and renders the toast viewport.
+
+
+```svelte
+// In your app root or layout
+<script lang="ts">
+  import { Toasty } from 'kumo-svelte';
+</script>
+
+<Toasty>
+  {@render children()}
+</Toasty>
+```
+
+</ComponentSection>
+
+<!-- Examples -->
+
+<ComponentSection>
+
+## Examples
+
+### Title and Description
+
+
+A complete toast with both title and description.
+
+<ComponentExample demo="ToastBasicDemo" />
+
+### Title Only
+
+
+A simple toast with just a title for brief messages.
+
+<ComponentExample demo="ToastTitleOnlyDemo" />
+
+### Description Only
+
+
+A toast with only a description for more detailed messages.
+
+<ComponentExample demo="ToastDescriptionOnlyDemo" />
+
+### Success Variant
+
+
+Use the success variant for confirmations and positive outcomes.
+
+<ComponentExample demo="ToastSuccessDemo" />
+
+### Multiple Toasts
+
+
+Multiple toasts stack and animate smoothly. Hover over the stack to expand
+  them.
+
+<ComponentExample demo="ToastMultipleDemo" />
+
+### Error Variant
+
+
+Use the error variant for critical issues that need attention.
+
+<ComponentExample demo="ToastErrorDemo" />
+
+### Warning Variant
+
+
+Use the warning variant for cautionary messages.
+
+<ComponentExample demo="ToastWarningDemo" />
+
+### Info Variant
+
+
+Use the info variant for neutral informational messages.
+
+<ComponentExample demo="ToastInfoDemo" />
+
+### Custom Content
+
+
+Use the content prop to render completely custom toast content.
+
+<ComponentExample demo="ToastCustomContentDemo" />
+
+### Action Buttons
+
+
+Add action buttons to toasts for user interaction.
+
+<ComponentExample demo="ToastActionsDemo" />
+
+### Promise
+
+
+Use the promise method to show loading, success, and error states
+  automatically.
+
+<ComponentExample demo="ToastPromiseDemo" />
+
+</ComponentSection>
+
+<!-- API Reference -->
+
+<ComponentSection>
+
+## API Reference
+
+### Toasty
+
+
+The provider component that wraps your app and manages the toast system.
+
+<PropsTable component="Toasty" />
+
+### useKumoToastManager()
+
+
+A hook that returns the toast manager for creating toasts.
+
+
+```svelte
+const toastManager = useKumoToastManager();
+
+// Add a toast
+toastManager.add(options);
+
+// Promise-based toast
+toastManager.promise(asyncFn(), {
+  loading: options,
+  success: (data) => options,
+  error: (err) => options,
+});
+```
+
+### Toast Options
+
+
+Options passed to `toastManager.add()` and promise handlers.
+
+<div class="overflow-x-auto">
+  <table class="w-full text-left text-sm">
+    <thead>
+      <tr class="border-b border-kumo-hairline">
+        <th class="py-3 pr-4 font-semibold">Prop</th>
+        <th class="py-3 pr-4 font-semibold">Type</th>
+        <th class="py-3 pr-4 font-semibold">Default</th>
+        <th class="py-3 font-semibold">Description</th>
+      </tr>
+    </thead>
+    <tbody class="text-kumo-subtle">
+      <tr class="border-b border-kumo-hairline">
+        <td class="py-3 pr-4 font-mono text-kumo-default">title</td>
+        <td class="py-3 pr-4 font-mono">string</td>
+        <td class="py-3 pr-4">—</td>
+        <td class="py-3">The toast title displayed prominently.</td>
+      </tr>
+      <tr class="border-b border-kumo-hairline">
+        <td class="py-3 pr-4 font-mono text-kumo-default">description</td>
+        <td class="py-3 pr-4 font-mono">string</td>
+        <td class="py-3 pr-4">—</td>
+        <td class="py-3">Secondary text displayed below the title.</td>
+      </tr>
+      <tr class="border-b border-kumo-hairline">
+        <td class="py-3 pr-4 font-mono text-kumo-default">variant</td>
+        <td class="py-3 pr-4 font-mono">
+          "default" | "success" | "error" | "warning" | "info"
+        </td>
+        <td class="py-3 pr-4 font-mono">"default"</td>
+        <td class="py-3">Visual style of the toast.</td>
+      </tr>
+      <tr class="border-b border-kumo-hairline">
+        <td class="py-3 pr-4 font-mono text-kumo-default">content</td>
+        <td class="py-3 pr-4 font-mono">Snippet</td>
+        <td class="py-3 pr-4">—</td>
+        <td class="py-3">
+          Custom content to render inside the toast. Overrides title and
+          description.
+        </td>
+      </tr>
+      <tr class="border-b border-kumo-hairline">
+        <td class="py-3 pr-4 font-mono text-kumo-default">actions</td>
+        <td class="py-3 pr-4 font-mono">ButtonProps[]</td>
+        <td class="py-3 pr-4">—</td>
+        <td class="py-3">Array of button props to render as action buttons.</td>
+      </tr>
+      <tr class="border-b border-kumo-hairline">
+        <td class="py-3 pr-4 font-mono text-kumo-default">timeout</td>
+        <td class="py-3 pr-4 font-mono">number</td>
+        <td class="py-3 pr-4 font-mono">5000</td>
+        <td class="py-3">
+          Time in milliseconds before the toast auto-dismisses.
+        </td>
+      </tr>
+    </tbody>
+  </table>
+</div>
+
+</ComponentSection>

package/src/routes/components/tooltip/+page.md

@@ -0,0 +1,125 @@
+---
+title: "Tooltip"
+description: "A popup that displays information related to an element when the element receives keyboard focus or the mouse hovers over it."
+sourceFile: "components/tooltip"
+baseUIComponent: "tooltip"
+---
+
+<script>
+  import ComponentExample from '$lib/docs/ComponentExample.svelte';
+  import ComponentSection from '$lib/docs/ComponentSection.svelte';
+  import PropsTable from '$lib/docs/PropsTable.svelte';
+</script>
+
+<!-- Hero Demo -->
+
+<ComponentSection>
+  <ComponentExample demo="TooltipHeroDemo" />
+</ComponentSection>
+
+<!-- Installation -->
+
+<ComponentSection>
+
+## Installation
+
+### Barrel
+
+```svelte
+import { Tooltip, TooltipProvider } from "kumo-svelte";
+```
+
+### Granular
+
+```svelte
+import { Tooltip, TooltipProvider } from "kumo-svelte";
+```
+
+</ComponentSection>
+
+<!-- Usage -->
+
+<ComponentSection>
+
+## Usage
+
+```svelte
+import { Tooltip, Button } from "kumo-svelte";
+
+<Tooltip content="Tooltip text">
+  <Button>Hover me</Button>
+</Tooltip>
+```
+
+For delay grouping across multiple tooltips, see [TooltipProvider](#tooltipprovider).
+
+</ComponentSection>
+
+<!-- Examples -->
+
+<ComponentSection>
+
+## Examples
+
+### Basic Tooltip
+
+<ComponentExample demo="TooltipBasicDemo" />
+
+### Multiple Tooltips
+
+<ComponentExample demo="TooltipMultipleDemo" />
+
+### Delay Control
+
+
+Use `delay` to control how long to wait before opening (default: 600ms) and
+  `closeDelay` to control how long to wait before closing (default: 0ms).
+
+<ComponentExample demo="TooltipDelayDemo" />
+
+</ComponentSection>
+
+<!-- TooltipProvider -->
+
+<span id="tooltipprovider"></span>
+
+<ComponentSection>
+## TooltipProvider
+
+
+`TooltipProvider` groups multiple tooltips so that after the first tooltip has
+  been shown, switching to another skips the open delay. Place it once at your
+  app root or layout — not around each individual `Tooltip`.
+
+
+```svelte
+// Wrap your app or layout once
+<TooltipProvider>
+  <App />
+</TooltipProvider>
+
+// Then use Tooltip anywhere inside
+<Tooltip content="Add">
+  <Button shape="square" aria-label="Add">
+    <PlusIcon />
+  </Button>
+</Tooltip>
+```
+
+</ComponentSection>
+
+<!-- API Reference -->
+
+<ComponentSection>
+
+## API Reference
+
+### Tooltip
+
+<PropsTable component="Tooltip" />
+
+### TooltipProvider
+
+<PropsTable component="Tooltip.Provider" />
+
+</ComponentSection>