kumo-svelte 0.1.0-beta.0

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

@@ -0,0 +1,383 @@
+---
+title: "Select"
+description: "Displays a list of options for the user to pick from—triggered by a button."
+sourceFile: "components/select"
+baseUIComponent: "select"
+---
+
+<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="SelectBasicDemo" />
+</ComponentSection>
+
+<!-- Installation -->
+
+<ComponentSection>
+
+## Installation
+
+### Barrel
+
+
+```svelte
+<script lang="ts">
+  import { Select } from 'kumo-svelte';
+</script>
+```
+
+### Granular
+
+```svelte
+<script lang="ts">
+  import { Select } from 'kumo-svelte';
+</script>
+```
+
+</ComponentSection>
+
+<!-- Usage -->
+
+<ComponentSection>
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { Select } from 'kumo-svelte';
+
+  let value = $state('apple');
+</script>
+
+<Select
+  label="Favorite Fruit"
+  bind:value
+  items={{ apple: 'Apple', banana: 'Banana', cherry: 'Cherry' }}
+/>
+```
+
+</ComponentSection>
+
+<!-- Examples -->
+
+<ComponentSection>
+
+## Examples
+
+### Basic
+
+
+A select with a visible label. When you provide the <code class="rounded bg-kumo-control px-1 py-0.5 text-sm">label</code> prop, the select automatically renders inside a Field wrapper with the label displayed above it.
+
+
+  <ComponentExample demo="SelectBasicDemo" />
+</ComponentSection>
+
+<!-- Sizes -->
+
+<ComponentSection>
+
+### Sizes
+
+
+Use the <code class="rounded bg-kumo-control px-1 py-0.5 text-sm">size</code> prop
+    to match Input sizing (xs, sm, base, lg).
+
+
+  <ComponentExample demo="SelectSizesDemo" />
+</ComponentSection>
+
+<!-- Without Visible Label -->
+
+<ComponentSection>
+
+### Without Visible Label
+
+
+When a visible label isn't needed (e.g., in compact UIs or when context is clear),
+    use `aria-label` for accessibility.
+
+
+  <ComponentExample demo="SelectWithoutLabelDemo" />
+</ComponentSection>
+
+<!-- With Description and Error -->
+
+<ComponentSection>
+
+### With Description and Error
+
+
+Select integrates with the Field wrapper to show description text and validation errors.
+
+
+  <ComponentExample demo="SelectWithFieldDemo" />
+</ComponentSection>
+
+<!-- Placeholder -->
+
+<ComponentSection>
+
+### Placeholder
+
+
+Use the <code class="rounded bg-kumo-control px-1 py-0.5 text-sm">placeholder</code> prop
+    to show text when no value is selected. When using <code class="rounded bg-kumo-control px-1 py-0.5 text-sm">renderValue</code> to
+    customize the display of selected values, the placeholder is shown instead of
+    calling <code class="rounded bg-kumo-control px-1 py-0.5 text-sm">renderValue</code> when the value is <code class="rounded bg-kumo-control px-1 py-0.5 text-sm">null</code>.
+
+
+```svelte
+<script lang="ts">
+  import { Select } from 'kumo-svelte';
+
+  type User = { id: string; name: string };
+  const users: User[] = [
+    { id: 'visal', name: 'Visal' },
+    { id: 'alice', name: 'Alice' }
+  ];
+  let user = $state('');
+</script>
+
+<Select
+  placeholder="Select a user..."
+  bind:value={user}
+  items={Object.fromEntries(users.map((user) => [user.id, user.name]))}
+/>
+```
+
+  <ComponentExample demo="SelectPlaceholderDemo" />
+</ComponentSection>
+
+<!-- Label Tooltip -->
+
+<ComponentSection>
+
+### Label with Tooltip
+
+
+Add a tooltip icon next to the label for additional context using <code
+      class="rounded bg-kumo-control px-1 py-0.5 text-sm">labelTooltip</code>.
+
+
+  <ComponentExample demo="SelectWithTooltipDemo" />
+</ComponentSection>
+
+<!-- Custom Rendering -->
+
+<ComponentSection>
+
+### Custom Rendering
+
+
+Use <code class="rounded bg-kumo-control px-1 py-0.5 text-sm">renderValue</code> to customize how the selected value
+    appears in the trigger button. This is useful when working with complex object
+    data structures instead of simple string values.
+
+
+<ComponentExample demo="SelectCustomRenderingDemo" />
+
+
+The <code class="rounded bg-kumo-control px-1 py-0.5 text-sm">renderValue</code> function is only called when a value is selected. Use <code class="rounded bg-kumo-control px-1 py-0.5 text-sm">placeholder</code> to define what to show when no value is selected.
+
+
+```svelte
+<script lang="ts">
+  import { Select } from 'kumo-svelte';
+
+  const languages = [
+    { value: 'en', label: 'English', emoji: 'GB' },
+    { value: 'fr', label: 'French', emoji: 'FR' },
+    { value: 'de', label: 'German', emoji: 'DE' }
+  ];
+
+  let value = $state('en');
+</script>
+
+<Select
+  class="w-[200px]"
+  placeholder="Select a language..."
+  bind:value
+  items={languages.map((language) => ({
+    value: language.value,
+    label: `${language.emoji} ${language.label}`
+  }))}
+/>
+```
+
+</ComponentSection>
+
+<!-- Loading -->
+
+<ComponentSection>
+
+### Loading
+
+
+A select component with loading state. The loading state is passed to
+    the component via the <code
+      class="rounded bg-kumo-control px-1 py-0.5 text-sm">loading</code> prop.
+
+
+  <ComponentExample demo="SelectLoadingDemo" />
+</ComponentSection>
+
+<!-- Multiple Item -->
+
+<ComponentSection>
+
+### Multiple Selection
+
+
+Enable multiple selection with the <code class="rounded bg-kumo-control px-1 py-0.5 text-sm">multiple</code> prop.
+    The value becomes an array of selected items. Use <code class="rounded bg-kumo-control px-1 py-0.5 text-sm">placeholder</code> for the empty state
+    and <code class="rounded bg-kumo-control px-1 py-0.5 text-sm">renderValue</code> to customize how selections are displayed.
+
+
+```svelte
+<script lang="ts">
+  import { Select } from 'kumo-svelte';
+
+  let selectedColumns = $state(['name', 'email']);
+</script>
+
+<Select
+  multiple
+  placeholder="Select columns..."
+  bind:value={selectedColumns}
+  renderValue={(columns) => columns.join(", ")}
+  items={{ name: "Name", email: "Email" }}
+/>
+```
+
+  <ComponentExample demo="SelectMultipleDemo" />
+</ComponentSection>
+
+<!-- More Example -->
+
+<ComponentSection>
+
+### More Example
+
+  <ComponentExample demo="SelectComplexDemo" />
+</ComponentSection>
+
+<!-- Disabled Options -->
+
+<ComponentSection>
+
+### Disabled Options
+
+
+Options can be disabled with the <code class="rounded bg-kumo-control px-1 py-0.5 text-sm">disabled</code> prop.
+    Disabled options are greyed out and cannot be selected.
+
+
+  <ComponentExample demo="SelectDisabledOptionsDemo" />
+</ComponentSection>
+
+<!-- Disabled Items via Prop -->
+
+<ComponentSection>
+
+### Disabled Items (via items prop)
+
+
+The <code class="rounded bg-kumo-control px-1 py-0.5 text-sm">items</code> object-map prop
+    accepts descriptor objects with <code class="rounded bg-kumo-control px-1 py-0.5 text-sm">disabled</code> alongside
+    plain string values.
+
+
+  <ComponentExample demo="SelectDisabledItemsDemo" />
+</ComponentSection>
+
+<!-- Grouped Options -->
+
+<ComponentSection>
+
+### Grouped Options
+
+
+Use <code class="rounded bg-kumo-control px-1 py-0.5 text-sm">Select.Group</code>,{" "}
+    <code class="rounded bg-kumo-control px-1 py-0.5 text-sm">Select.GroupLabel</code>, and{" "}
+    <code class="rounded bg-kumo-control px-1 py-0.5 text-sm">Select.Separator</code> to
+    organize options under labeled headers with visual dividers.
+
+
+  <ComponentExample demo="SelectGroupedDemo" />
+</ComponentSection>
+
+<!-- Groups with Disabled -->
+
+<ComponentSection>
+
+### Groups with Disabled Options
+
+
+Combine groups, separators, and disabled options with info tooltips to
+    clearly separate available and unavailable choices.
+
+
+  <ComponentExample demo="SelectGroupedWithDisabledDemo" />
+</ComponentSection>
+
+<!-- Long List - Test scrolling behavior -->
+
+<ComponentSection>
+
+### Long List (Scrolling Test)
+
+
+A select component with many options to test popup scrolling behavior.
+    The popup should scroll smoothly without bounce/overscroll issues.
+
+
+  <ComponentExample demo="SelectLongListDemo" />
+</ComponentSection>
+
+<!-- API Reference -->
+
+<ComponentSection>
+
+## API Reference
+
+### Select
+
+  <PropsTable component="Select" />
+
+### Select.Option
+
+<PropsTable component="Select.Option" />
+
+### Select.Group
+
+
+Groups related options together with an accessible{" "}
+  <code class="rounded bg-kumo-control px-1 py-0.5 text-sm">role="group"</code>.
+  Use with{" "}
+  <code class="rounded bg-kumo-control px-1 py-0.5 text-sm">
+    Select.GroupLabel
+  </code>{" "}
+  to provide a visible heading.
+
+
+### Select.GroupLabel
+
+
+A visible heading for a{" "}
+  <code class="rounded bg-kumo-control px-1 py-0.5 text-sm">Select.Group</code>.
+  Automatically associated with its parent group for accessibility.
+
+
+### Select.Separator
+
+
+A visual divider line between option groups. Renders with <code class="rounded bg-kumo-control px-1 py-0.5 text-sm">role="separator"</code>.
+
+</ComponentSection>

package/src/routes/components/sensitive-input/+page.md

@@ -0,0 +1,103 @@
+---
+title: "Sensitive Input"
+description: "A masked input for sensitive values like API keys and passwords. Click to reveal."
+sourceFile: "components/sensitive-input"
+---
+
+<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="SensitiveInputDemo" />
+</ComponentSection>
+
+<!-- Installation -->
+
+<ComponentSection>
+
+## Installation
+
+### Barrel
+
+```svelte
+<script lang="ts">
+  import { SensitiveInput } from 'kumo-svelte';
+</script>
+```
+
+### Granular
+
+```svelte
+<script lang="ts">
+  import { SensitiveInput } from 'kumo-svelte';
+</script>
+```
+
+</ComponentSection>
+
+<!-- Usage -->
+
+<ComponentSection>
+
+## Usage
+
+```svelte
+<script lang="ts">
+  import { SensitiveInput } from 'kumo-svelte';
+</script>
+
+<SensitiveInput label="Secret" defaultValue="my-secret-key" />
+```
+
+</ComponentSection>
+
+<!-- Sizes -->
+
+<ComponentSection>
+
+## Sizes
+
+
+SensitiveInput supports multiple sizes to fit different contexts.
+
+  <ComponentExample demo="SensitiveInputSizesDemo" />
+</ComponentSection>
+
+<!-- Controlled -->
+
+<ComponentSection>
+
+## Controlled
+
+
+Use controlled mode for full control over the input value.
+
+  <ComponentExample demo="SensitiveInputControlledDemo" />
+</ComponentSection>
+
+<!-- States -->
+
+<ComponentSection>
+
+## States
+
+
+Various input states including error, disabled, read-only, and with
+    description.
+
+  <ComponentExample demo="SensitiveInputStatesDemo" />
+</ComponentSection>
+
+<!-- API Reference -->
+
+<ComponentSection>
+
+## API Reference
+
+  <PropsTable component="SensitiveInput" />
+</ComponentSection>

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

@@ -0,0 +1,58 @@
+---
+title: "Sidebar"
+description: "Responsive navigation sidebar component."
+---
+
+<script>
+  import Callout from '$lib/docs/Callout.svelte';
+  import ComponentExample from '$lib/docs/ComponentExample.svelte';
+  import ComponentSection from '$lib/docs/ComponentSection.svelte';
+  import CodeBlock from '$lib/docs/CodeBlock.svelte';
+  import PropsTable from '$lib/docs/PropsTable.svelte';
+
+  const sidebarUsage = `<script lang="ts">
+  import { Sidebar } from 'kumo-svelte';
+<\/script>
+
+<Sidebar>
+  <a href="/dashboard">Dashboard</a>
+  <a href="/workers">Workers</a>
+  <a href="/settings">Settings</a>
+</Sidebar>`;
+</script>
+
+<ComponentSection title="Overview">
+
+Sidebar provides a persistent navigation surface for documentation and application shells. It is used by the Kumo docs layout for the desktop rail, expanded navigation panel, and mobile drawer.
+
+</ComponentSection>
+
+<ComponentSection title="Example">
+
+<ComponentExample title="Basic sidebar">
+  <div class="w-72 rounded-lg border border-kumo-hairline bg-kumo-canvas p-3 text-sm">
+    <button class="mb-3 flex w-full items-center gap-2 rounded-lg bg-kumo-control px-3 py-2 text-kumo-subtle ring-1 ring-kumo-line">
+      Search...
+    </button>
+    <nav class="space-y-px">
+      <a class="block rounded-lg bg-kumo-tint p-2 font-semibold text-kumo-default" href="/installation">Installation</a>
+      <a class="block rounded-lg p-2 text-kumo-subtle hover:bg-kumo-tint hover:text-kumo-default" href="/components/button">Button</a>
+      <a class="block rounded-lg p-2 text-kumo-subtle hover:bg-kumo-tint hover:text-kumo-default" href="/components/input">Input</a>
+      <a class="block rounded-lg p-2 text-kumo-subtle hover:bg-kumo-tint hover:text-kumo-default" href="/components/select">Select</a>
+    </nav>
+  </div>
+</ComponentExample>
+
+</ComponentSection>
+
+<ComponentSection title="Usage">
+
+<CodeBlock lang="svelte" code={sidebarUsage} />
+
+</ComponentSection>
+
+<ComponentSection title="API Reference">
+
+<PropsTable component="Sidebar" />
+
+</ComponentSection>

package/src/routes/components/skeleton-line/+page.md

@@ -0,0 +1,146 @@
+---
+title: "Skeleton Line"
+description: "A skeleton loading placeholder for text content."
+sourceFile: "primitives/skeleton-line"
+---
+
+<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="SkeletonLineDemo" />
+</ComponentSection>
+
+<!-- Installation -->
+
+<ComponentSection>
+
+## Installation
+
+```svelte
+<script lang="ts">
+  import { SkeletonLine } from 'kumo-svelte';
+</script>
+
+<SkeletonLine />
+```
+
+</ComponentSection>
+
+<!-- Custom Widths -->
+
+<ComponentSection>
+
+## Custom Widths
+
+  <p class="mb-4">
+    Control the randomized width range for more natural-looking skeletons.
+  </p>
+  <ComponentExample demo="SkeletonLineWidthDemo" />
+</ComponentSection>
+
+<!-- Custom Height -->
+
+<ComponentSection>
+
+## Custom Height
+
+  <p class="mb-4">
+    Override the default height using Tailwind utility classes via{" "}
+    <code>class</code>. The default height is <code>0.5rem</code>.
+  </p>
+  <ComponentExample demo="SkeletonLineHeightDemo" />
+</ComponentSection>
+
+<!-- Block Height -->
+
+<ComponentSection>
+
+## Block Height
+
+  <p class="mb-4">
+    Use <code>blockHeight</code> to set the height of a container that
+    vertically centers the skeleton line. Useful when replacing text of a known
+    line height. Accepts a number (treated as <code>px</code>) or any CSS string
+    value.
+  </p>
+  <ComponentExample demo="SkeletonLineBlockHeightDemo" />
+</ComponentSection>
+
+<!-- Card Loading State -->
+
+<ComponentSection>
+
+## Card Loading State
+
+  <p class="mb-4">
+    Use skeleton lines to create loading states for cards and content areas.
+  </p>
+  <ComponentExample demo="SkeletonLineCardDemo" />
+</ComponentSection>
+
+<!-- API Reference -->
+
+<ComponentSection>
+
+## API Reference
+
+  <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">Prop</th>
+          <th class="px-4 py-3 text-left font-semibold">Type</th>
+          <th class="px-4 py-3 text-left font-semibold">Default</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr class="border-b border-kumo-hairline">
+          <td class="px-4 py-3 font-mono text-xs">minWidth</td>
+          <td class="px-4 py-3 font-mono text-xs">number</td>
+          <td class="px-4 py-3 font-mono text-xs">30</td>
+        </tr>
+        <tr class="border-b border-kumo-hairline">
+          <td class="px-4 py-3 font-mono text-xs">maxWidth</td>
+          <td class="px-4 py-3 font-mono text-xs">number</td>
+          <td class="px-4 py-3 font-mono text-xs">100</td>
+        </tr>
+        <tr class="border-b border-kumo-hairline">
+          <td class="px-4 py-3 font-mono text-xs">minDuration</td>
+          <td class="px-4 py-3 font-mono text-xs">number</td>
+          <td class="px-4 py-3 font-mono text-xs">1.3</td>
+        </tr>
+        <tr class="border-b border-kumo-hairline">
+          <td class="px-4 py-3 font-mono text-xs">maxDuration</td>
+          <td class="px-4 py-3 font-mono text-xs">number</td>
+          <td class="px-4 py-3 font-mono text-xs">1.7</td>
+        </tr>
+        <tr class="border-b border-kumo-hairline">
+          <td class="px-4 py-3 font-mono text-xs">minDelay</td>
+          <td class="px-4 py-3 font-mono text-xs">number</td>
+          <td class="px-4 py-3 font-mono text-xs">0</td>
+        </tr>
+        <tr class="border-b border-kumo-hairline">
+          <td class="px-4 py-3 font-mono text-xs">maxDelay</td>
+          <td class="px-4 py-3 font-mono text-xs">number</td>
+          <td class="px-4 py-3 font-mono text-xs">0.5</td>
+        </tr>
+        <tr class="border-b border-kumo-hairline">
+          <td class="px-4 py-3 font-mono text-xs">blockHeight</td>
+          <td class="px-4 py-3 font-mono text-xs">string | number</td>
+          <td class="px-4 py-3 font-mono text-xs">-</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">-</td>
+        </tr>
+      </tbody>
+    </table>
+  </div>
+</ComponentSection>