kumo-svelte 0.1.0-beta.0

package/src/routes/charts/custom/+page.md

@@ -0,0 +1,34 @@
+---
+title: "Custom Chart"
+description: "Example charts using the Chart component."
+sourceFile: "components/chart"
+---
+
+<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';
+</script>
+
+
+<ComponentSection>
+
+## Custom Chart
+
+<ComponentExample demo="PieChartDemo" />
+
+</ComponentSection>
+
+<ComponentSection>
+
+## Custom Tooltip with HTML
+
+For tooltips that require custom HTML formatting, use the `dangerousHtmlFormatter` property instead of the standard `formatter`. This makes the security implications more explicit.
+
+When using `dangerousHtmlFormatter`, it is **strongly recommended** to sanitize any user-provided content using `echarts.format.encodeHTML` to prevent XSS vulnerabilities.
+
+<ComponentExample demo="CustomTooltipChartDemo" />
+
+</ComponentSection>

package/src/routes/charts/sankey/+page.md

@@ -0,0 +1,75 @@
+---
+title: "Sankey Chart"
+description: "A Sankey diagram component for visualizing flow data between nodes using ECharts."
+sourceFile: "components/chart"
+---
+
+<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';
+</script>
+
+<ComponentSection>
+
+<ComponentExample demo="SankeyChartBasicDemo" />
+
+</ComponentSection>
+
+<ComponentSection>
+
+## Installation
+
+SankeyChart requires <code class="text-kumo-default">echarts</code> as a peer dependency.
+
+```bash
+npm install echarts
+```
+
+```svelte
+import { SankeyChart } from "kumo-svelte";
+```
+
+</ComponentSection>
+
+<ComponentSection>
+
+## Examples
+
+### Basic Sankey
+
+A simple Sankey diagram showing flow between source and target nodes.
+
+<ComponentExample demo="SankeyChartBasicDemo" />
+
+### Multi-level Flow
+
+Sankey diagrams can show multiple levels of flow through intermediate nodes.
+
+<ComponentExample demo="SankeyChartMultiLevelDemo" />
+
+### Full Width
+
+Use <code class="text-kumo-default">left</code> and <code class="text-kumo-default">right</code> to control horizontal padding of the Sankey layout within its container.
+
+<ComponentExample demo="SankeyChartFullWidthDemo" />
+
+### Custom Tooltip
+
+<ComponentExample demo="SankeyChartTooltipDemo" />
+
+### Rich Tooltip
+
+<ComponentExample demo="SankeyChartRichTooltipDemo" />
+
+### Interactive
+
+<ComponentExample demo="SankeyChartInteractiveDemo" />
+
+### Drill Down
+
+<ComponentExample demo="SankeyChartDrillDownDemo" />
+
+</ComponentSection>

package/src/routes/charts/timeseries/+page.md

@@ -0,0 +1,97 @@
+---
+title: "Timeseries Chart"
+description: "A specialized chart for displaying time-based data."
+sourceFile: "components/chart"
+---
+
+<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';
+</script>
+
+
+The timeseries chart is a specialized chart for displaying time-based data.
+  Each data point is a tuple of <code>[timestamp_in_ms, value]</code>.
+
+<ComponentSection>
+
+### Basic Line Chart
+
+A simple line chart displaying multiple data series over time.
+
+<ComponentExample demo="BasicLineChartDemo" />
+
+</ComponentSection>
+
+<ComponentSection>
+
+### Custom X-Axis Label Format
+
+  Use the <code>xAxisTickLabelFormat</code> prop to control how x-axis tick
+  labels are rendered. The formatter receives the raw timestamp in milliseconds
+  and returns a display string, overriding ECharts' built-in time formatting.
+
+<ComponentExample demo="CustomAxisLabelFormatDemo" />
+
+</ComponentSection>
+
+<ComponentSection>
+
+### Gradient Fill
+
+  Set <code>gradient</code> to <code>true</code> to render a vertical gradient
+  fill beneath each line series. The fill fades from the series color at the top
+  to transparent at the bottom, giving the chart a polished area-chart look
+  without losing the clarity of individual lines.
+
+<ComponentExample demo="GradientLineChartDemo" />
+
+</ComponentSection>
+
+<ComponentSection>
+
+### Incomplete Data
+
+  Use the <code>incomplete</code> prop to indicate regions where data may be
+  incomplete or still being collected.
+
+<ComponentExample demo="IncompleteDataChartDemo" />
+
+</ComponentSection>
+
+<ComponentSection>
+
+### Time Range Selection
+
+  Enable time range selection by providing the <code>onTimeRangeChange</code>
+  callback. Users can click and drag on the chart to select a time range.
+
+<ComponentExample demo="TimeRangeSelectionChartDemo" />
+
+</ComponentSection>
+
+<ComponentSection>
+
+### Bar Chart
+
+  Set <code>type="bar"</code> to render series as stacked bars instead of lines.
+  All other props — axes, tooltips, colors — work identically.
+
+<ComponentExample demo="BarChartDemo" />
+
+</ComponentSection>
+
+<ComponentSection>
+
+### Loading State
+
+  Set <code>loading</code> to <code>true</code> to display an animated sine-wave
+  skeleton while data is being fetched. The chart canvas is hidden until loading
+  completes; swap back to <code>loading=false</code> to reveal the chart.
+
+<ComponentExample demo="LoadingChartDemo" />
+
+</ComponentSection>

package/src/routes/cli/+page.md

@@ -0,0 +1,74 @@
+---
+title: "CLI"
+description: "Access component documentation and install blocks from your terminal."
+---
+
+<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';
+</script>
+
+
+## Installation
+
+The Kumo CLI is available via npx. No installation required.
+
+```bash
+npx kumo-svelte help
+```
+
+## Commands
+
+### Blocks
+
+Install copy-paste blocks into your project for full customization.
+
+```bash
+# Initialize kumo.json configuration
+npx kumo-svelte init
+
+# List all available blocks
+npx kumo-svelte blocks
+
+# Install a block to your project
+npx kumo-svelte add PageHeader
+```
+
+### Component Registry
+
+Access component documentation directly from your terminal.
+
+```bash
+# List all Kumo components with categories
+npx kumo-svelte ls
+
+# Get detailed documentation for a component
+npx kumo-svelte doc Button
+
+# Get documentation for all components
+npx kumo-svelte docs
+```
+
+### Migration and AI
+
+Export token rename maps for codebase migrations and print the AI usage guide.
+
+```bash
+# Show pending token migrations
+npx kumo-svelte migrate
+
+# Show class-level mappings
+npx kumo-svelte migrate --classes
+
+# Print the AI component usage guide
+npx kumo-svelte ai
+```
+
+## Try it out
+
+Type commands in the interactive terminal below to explore the CLI.
+
+<p class="not-prose my-4 rounded-lg border border-kumo-hairline bg-kumo-canvas p-4 text-sm text-kumo-subtle">CLITerminal</p>

package/src/routes/colors/+page.md

@@ -0,0 +1,316 @@
+---
+title: "Colors"
+description: "Kumo uses semantic color tokens that automatically adapt to light and dark mode. Use these classes in your Tailwind CSS instead of raw color values."
+---
+
+<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';
+</script>
+
+
+## Usage
+
+Always use semantic tokens instead of raw Tailwind colors. This ensures your UI automatically adapts to light and dark mode, and that your components remain consistent across themes.
+
+#### Correct
+
+```svelte
+<div class="bg-kumo-base text-kumo-default border-kumo-hairline">
+  <button class="bg-kumo-brand text-white">Primary</button>
+  <button class="bg-kumo-control text-kumo-default">Secondary</button>
+</div>
+```
+
+#### Incorrect
+
+```svelte
+{
+  /* Never use raw Tailwind colors */
+}
+<div class="bg-white dark:bg-gray-900 text-black dark:text-white">
+  <button class="bg-blue-500">Primary</button>
+</div>;
+```
+
+> Lint rules enforce this: The `no-primitive-colors` rule will flag any raw Tailwind colors like `bg-blue-500`.
+
+## Mode
+
+Set `data-mode` on a parent element to control light/dark mode. Never use Tailwind's `dark:` variant — semantic tokens handle dark mode automatically via CSS `light-dark()`.
+
+```svelte
+// Set mode on html or body
+<html data-mode="light">  // Light mode
+<html data-mode="dark">   // Dark mode
+
+// Components automatically adapt - no dark: variants needed
+<div class="bg-kumo-base text-kumo-default" />
+```
+
+## Themes
+
+Themes override semantic token values while preserving the same token names. Set `data-theme` on a parent element to apply a theme.
+
+### Available Themes
+
+- `kumo` — Default theme (no attribute needed)
+- `fedramp` — Government compliance styling
+
+```svelte
+// Apply a theme to a section or the whole app
+<div data-theme="fedramp">
+  {/* All Kumo components inside use fedramp token overrides */}
+  <Button>FedRAMP Styled</Button>
+</div>
+
+// Themes work with both light and dark mode
+<html data-mode="dark" data-theme="fedramp">
+```
+
+### Theme Generator
+
+Themes are defined in a centralized config and generated as CSS files. The theme generator ensures consistency across all themes.
+
+```bash
+
+# List all tokens and their theme overrides
+
+pnpm --filter kumo-svelte codegen:themes --list
+
+# Generate theme CSS files
+
+pnpm --filter kumo-svelte codegen:themes
+
+# Preview changes without writing files
+
+pnpm --filter kumo-svelte codegen:themes --dry-run
+```
+
+Theme config: `packages/kumo/scripts/theme-generator/config.ts`
+
+### Creating a New Theme
+
+Add theme overrides in the config file. Only override tokens that need to change — all other tokens inherit from the base kumo theme.
+
+```ts
+// In scripts/theme-generator/config.ts
+
+// Add to available themes
+```
+
+Then run `pnpm codegen:themes` to generate the CSS.
+
+## Semantic Tokens
+
+We use semantic tokens to group colors by purpose. Use the token that matches the role of the element, not the color you want to achieve.
+
+Semantic tokens are named by **role**, not by hue. A token like `bg-kumo-danger` communicates intent — it doesn't imply a specific shade of red, and its exact value can change per theme or color mode without touching your component code.
+
+### Surface Hierarchy
+
+Surfaces establish depth and layering in the UI. Use them in order from the outermost background inward.
+
+  <table>
+    <colgroup>
+      <col style="width: 22ch;" />
+      <col />
+    </colgroup>
+    <thead>
+      <tr>
+        <th>Token</th>
+        <th>Purpose</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td><code>bg-kumo-canvas</code></td>
+        <td>The outermost page background — sits behind everything</td>
+      </tr>
+      <tr>
+        <td><code>bg-kumo-base</code></td>
+        <td>Default component background</td>
+      </tr>
+      <tr>
+        <td><code>bg-kumo-elevated</code></td>
+        <td>Slightly elevated surface, e.g. <code>LayerCard.Secondary</code></td>
+      </tr>
+      <tr>
+        <td><code>bg-kumo-recessed</code></td>
+        <td>Recessed surface with a subtly darker fill, e.g. segmented <code>Tabs</code> background</td>
+      </tr>
+      <tr>
+        <td><code>bg-kumo-tint</code></td>
+        <td>Subtle tinted background for tables or hover states</td>
+      </tr>
+      <tr>
+        <td><code>bg-kumo-contrast</code></td>
+        <td>High-contrast, inverted background</td>
+      </tr>
+    </tbody>
+  </table>
+
+### Brand
+
+  <table>
+    <colgroup>
+      <col style="width: 22ch;" />
+      <col />
+    </colgroup>
+    <thead>
+      <tr>
+        <th>Token</th>
+        <th>Purpose</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td><code>bg-kumo-brand</code></td>
+        <td>Primary brand background</td>
+      </tr>
+      <tr>
+        <td><code>bg-kumo-brand-hover</code></td>
+        <td>Hover state for brand backgrounds</td>
+      </tr>
+    </tbody>
+  </table>
+
+### Semantic Status Colors
+
+Each status color comes in two variants: a solid color for icons and indicators, and a `-tint` variant for background fills behind content (i.e. `Badge` or `Banner`).
+
+  <table>
+    <colgroup>
+      <col style="width: 22ch;" />
+      <col />
+    </colgroup>
+    <thead>
+      <tr>
+        <th>Token</th>
+        <th>Purpose</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td><code>bg-kumo-info</code></td>
+        <td>Info indicator (icon, dot, bar)</td>
+      </tr>
+      <tr>
+        <td><code>bg-kumo-success</code></td>
+        <td>Success indicator</td>
+      </tr>
+      <tr>
+        <td><code>bg-kumo-warning</code></td>
+        <td>Warning indicator</td>
+      </tr>
+      <tr>
+        <td><code>bg-kumo-danger</code></td>
+        <td>Error/destructive indicator</td>
+      </tr>
+    </tbody>
+  </table>
+
+Use the solid token on icons, status dots, borders and rings. Banners and badges use the `-tint` variant with varying opacity values for the different instances.
+
+```svelte
+// Banner with tinted background and solid icon
+<div class="bg-kumo-danger-tint text-kumo-danger">
+  <AlertIcon class="text-kumo-danger" />
+  <p>Something went wrong.</p>
+</div>
+```
+
+### Text Colors
+
+  <table>
+    <colgroup>
+      <col style="width: 22ch;" />
+      <col />
+    </colgroup>
+    <thead>
+      <tr>
+        <th>Token</th>
+        <th>Purpose</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td><code>text-kumo-default</code></td>
+        <td>Primary body text</td>
+      </tr>
+      <tr>
+        <td><code>text-kumo-strong</code></td>
+        <td>Stronger text contrast than default for headers and important labels</td>
+      </tr>
+      <tr>
+        <td><code>text-kumo-subtle</code></td>
+        <td>Muted text for descriptions, captions, or secondary labels</td>
+      </tr>
+      <tr>
+        <td><code>text-kumo-inactive</code></td>
+        <td>Disabled or inactive text</td>
+      </tr>
+      <tr>
+        <td><code>text-kumo-placeholder</code></td>
+        <td>Placeholder text in inputs</td>
+      </tr>
+      <tr>
+        <td><code>text-kumo-inverse</code></td>
+        <td>Text intended for use on high-contrast or inverted backgrounds</td>
+      </tr>
+      <tr>
+        <td><code>text-kumo-link</code></td>
+        <td>Link text</td>
+      </tr>
+      <tr>
+        <td><code>text-kumo-info</code></td>
+        <td>Info-colored text</td>
+      </tr>
+      <tr>
+        <td><code>text-kumo-success</code></td>
+        <td>Success-colored text</td>
+      </tr>
+      <tr>
+        <td><code>text-kumo-warning</code></td>
+        <td>Warning-colored text</td>
+      </tr>
+      <tr>
+        <td><code>text-kumo-danger</code></td>
+        <td>Error/destructive text</td>
+      </tr>
+    </tbody>
+  </table>
+
+### Borders & Rings
+
+  <table>
+    <colgroup>
+      <col style="width: 22ch;" />
+      <col />
+    </colgroup>
+    <thead>
+      <tr>
+        <th>Token</th>
+        <th>Purpose</th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr>
+        <td><code>kumo-hairline</code><div class="not-prose my-4 rounded-lg border border-kumo-hairline bg-kumo-canvas p-4 text-sm text-kumo-subtle">New</div></td>
+        <td>A border/ring color to distinguish between flat surfaces where no shadow is present (i.e. <code>LayerCard</code>).</td>
+      </tr>
+      <tr>
+        <td><code>kumo-hairline</code></td>
+        <td>A thicker border/ring color that defines the edge of an elevated surface alongside a shadow.</td>
+      </tr>
+    </tbody>
+  </table>
+
+## Token Reference
+
+Toggle the theme in the header to see how tokens adapt. Tokens marked as "global" are explicit opt-in classes available regardless of theme.
+
+<p class="not-prose my-4 rounded-lg border border-kumo-hairline bg-kumo-canvas p-4 text-sm text-kumo-subtle">TailwindColorTokens</p>