kumo-svelte 0.1.0-beta.0

package/src/routes/[...path]/+page.svelte

@@ -0,0 +1,21 @@
+<script lang="ts">
+  interface Props {
+    data: {
+      title: string;
+    };
+  }
+
+  let { data }: Props = $props();
+</script>
+
+<main class="flex grow flex-col md:pr-12">
+  <div class="mx-auto w-full grow md:border-r md:border-kumo-hairline">
+    <article class="mx-auto max-w-3xl px-6 py-16">
+      <p class="mb-3 font-mono text-sm text-kumo-subtle">kumo-svelte</p>
+      <h1 class="text-4xl font-semibold tracking-tight text-kumo-default">{data.title}</h1>
+      <p class="mt-4 text-base text-kumo-subtle">
+        This route is wired into the faithful Kumo docs shell and is ready for the corresponding upstream page port.
+      </p>
+    </article>
+  </div>
+</main>

package/src/routes/[...path]/+page.ts

@@ -0,0 +1,10 @@
+import { blockItems, chartItems, componentItems, staticPages } from '$lib/docs/nav';
+
+export function load({ url }) {
+  const allItems = [...staticPages, ...componentItems, ...chartItems, ...blockItems];
+  const item = allItems.find((entry) => entry.href === url.pathname);
+
+  return {
+    title: item?.label ?? 'Kumo'
+  };
+}

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

@@ -0,0 +1,47 @@
+---
+title: "Accessibility"
+description: "Learn how to make the most of Kumo's accessibility features and guidelines."
+---
+
+<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>
+
+
+Accessibility is a top priority for Kumo. Built on [Base UI](https://base-ui.com/react/overview/accessibility), Kumo components handle many complex accessibility details including ARIA attributes, role attributes, pointer interactions, keyboard navigation, and focus management. The goal is to provide an accessible user experience out of the box, with intuitive APIs for configuration.
+
+This page highlights some of the key accessibility features of Kumo, as well as some ways you will need to augment the library, in order to ensure that your application is accessible to everyone.
+
+## Keyboard Navigation
+
+Kumo components adhere to the [WAI-ARIA Authoring Practices](https://www.w3.org/WAI/ARIA/apg/) to provide basic keyboard accessibility out of the box. This is critical for users who have difficulty using a pointer device, but it's also important for users who prefer navigating with a keyboard or other input mode.
+
+Many components provide support for arrow keys, alphanumeric keys, <kbd>Home</kbd>, <kbd>End</kbd>, <kbd>Enter</kbd>, and <kbd>Esc</kbd>.
+
+## Focus Management
+
+Kumo components manage focus automatically following a user interaction. Additionally, some components provide props like `initialFocus` and `finalFocus`, to configure focus management.
+
+While Kumo components manage focus, it's the developer's responsibility to visually indicate focus. This is typically handled by styling the `:focus` or `:focus-visible` CSS pseudo-classes. [WCAG provides guidelines on focus appearance](https://www.w3.org/WAI/WCAG21/Understanding/focus-visible.html).
+
+## Color Contrast
+
+When styling elements, it's important to meet the minimum requirements for color contrast between each foreground element and its corresponding background element. Unless your application has strict requirements around compliance with current standards, consider adhering to [APCA](https://www.myndex.com/APCA/), which is slated to become the new standard in WCAG 3.
+
+## Accessible Labels
+
+Kumo provides components like `Field`, `Input`, and `Checkbox` to automatically associate form controls. Additionally, you can use the native HTML `&lt;label&gt;` element to provide context to corresponding inputs.
+
+Most applications will present custom controls that require accessible names provided by markup features such as `alt`, `aria-label` or `aria-labelledby`. [WAI-ARIA provides guidelines on providing accessible names to custom controls](https://www.w3.org/WAI/ARIA/apg/practices/names-and-descriptions/).
+
+## Testing
+
+Kumo components, built on Base UI, are tested on a broad spectrum of browsers, devices, platforms, screen readers, and environments to ensure accessibility across different user contexts.
+
+---
+
+For more detailed information about the accessibility features provided by Base UI, visit the [official accessibility documentation](https://base-ui.com/react/overview/accessibility).

package/src/routes/blocks/delete-resource/+page.md

@@ -0,0 +1,91 @@
+---
+title: "Delete Resource"
+description: "A confirmation dialog for safely deleting resources, requiring users to type the resource name to confirm."
+sourceFile: "blocks/delete-resource"
+---
+
+<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>
+
+
+<!-- Hero Demo -->
+
+<ComponentSection>
+
+<ComponentExample demo="DeleteResourceBasicDemo" />
+
+</ComponentSection>
+
+<!-- Installation -->
+
+<ComponentSection>
+
+## Installation
+
+  
+    DeleteResource is a <strong>block</strong> - a CLI-installed component that
+    you own and can customize. Unlike regular components, blocks are copied into
+    your project so you have full control over the code.
+  
+  
+    
+      **1. Initialize Kumo config (first time only)**
+
+```bash
+npx kumo-svelte init
+```
+
+**2. Install the block**
+
+```bash
+npx kumo-svelte add DeleteResource
+```
+
+**3. Import from your local path**
+
+```svelte
+<script lang="ts">
+  import { DeleteResource } from './delete-resource';
+</script>
+
+<DeleteResource resourceType="Zone" resourceName="example.com" />
+```
+
+</ComponentSection>
+
+<!-- Examples -->
+
+<ComponentSection>
+
+## Examples
+
+### Worker Deletion
+
+  Works with any resource type - just change the resourceType and resourceName
+  props.
+
+<ComponentExample demo="DeleteResourceWorkerDemo" />
+
+### Error State
+
+  
+    Use the errorMessage prop to show an error message.
+
+<ComponentExample demo="DeleteResourceErrorDemo" />
+
+</ComponentSection>
+
+<!-- API Reference -->
+
+<ComponentSection>
+
+## API Reference
+
+<PropsTable component="DeleteResource"  />
+
+</ComponentSection>

package/src/routes/blocks/page-header/+page.md

@@ -0,0 +1,136 @@
+---
+title: "Page Header"
+description: "A composite component that combines breadcrumbs and tabs for page navigation."
+sourceFile: "blocks/page-header"
+---
+
+<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>
+
+
+<!-- Hero Demo -->
+
+<ComponentSection>
+
+<ComponentExample demo="PageHeaderHeroDemo" />
+
+</ComponentSection>
+
+<!-- Installation -->
+
+<ComponentSection>
+
+## Installation
+
+  
+    PageHeader is a <strong>block</strong> - a CLI-installed component that you
+    own and can customize. Unlike regular components, blocks are copied into
+    your project so you have full control over the code.
+  
+  
+    
+      **1. Initialize Kumo config (first time only)**
+
+```bash
+npx kumo-svelte init
+```
+
+**2. Install the block**
+
+```bash
+npx kumo-svelte add PageHeader
+```
+
+**3. Import from your local path**
+
+```svelte
+<script lang="ts">
+  import { PageHeader } from './page-header';
+
+  let activeTab = $state('overview');
+</script>
+
+<PageHeader
+  breadcrumbs={[{ label: 'Home', href: '/' }, { label: 'Projects' }]}
+  title="My Project"
+  tabs={[{ label: 'Overview', value: 'overview' }, { label: 'Settings', value: 'settings' }]}
+  bind:activeTab
+/>
+```
+
+</ComponentSection>
+
+<!-- Examples -->
+
+<ComponentSection>
+
+## Examples
+
+### Basic
+
+<ComponentExample demo="PageHeaderBasicDemo" />
+
+### With Icons
+
+<ComponentExample demo="PageHeaderWithIconsDemo" />
+
+### With Tabs
+
+<ComponentExample demo="PageHeaderWithTabsDemo" />
+
+### With Actions
+
+<ComponentExample demo="PageHeaderWithActionsDemo" />
+
+### With Title
+
+<ComponentExample demo="PageHeaderWithTitleDemo" />
+
+### With Title and Description
+
+<ComponentExample demo="PageHeaderWithTitleDescriptionDemo" />
+
+### Complete Example
+
+  Combining breadcrumbs, title, description, tabs, and actions.
+
+<ComponentExample demo="PageHeaderCompleteDemo" />
+
+</ComponentSection>
+
+<!-- API Reference -->
+
+<ComponentSection>
+
+## API Reference
+
+<PropsTable component="PageHeader"  />
+
+### TabsItem
+
+  
+    <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>
+        </tr>
+      </thead>
+      <tbody>
+        <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</td>
+        </tr>
+        <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>
+        </tr>
+      </tbody>
+    </table>
+
+</ComponentSection>

package/src/routes/blocks/resource-list/+page.md

@@ -0,0 +1,145 @@
+---
+title: "Resource List"
+description: "A layout component for resource list pages with optional sidebar content."
+sourceFile: "blocks/resource-list"
+---
+
+<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>
+
+
+<!-- Hero Demo -->
+
+<ComponentSection>
+
+<ComponentExample demo="ResourceListCompleteDemo" />
+
+</ComponentSection>
+
+<!-- Installation -->
+
+<ComponentSection>
+
+## Installation
+
+  
+    ResourceListPage is a <strong>block</strong> - a CLI-installed component
+    that you own and can customize. Unlike regular components, blocks are copied
+    into your project so you have full control over the code.
+  
+  
+    
+      **1. Initialize Kumo config (first time only)**
+
+```bash
+npx kumo-svelte init
+```
+
+**2. Install the block**
+
+```bash
+npx kumo-svelte add ResourceListPage
+```
+
+**3. Import from your local path**
+
+```svelte
+<script lang="ts">
+  import { Badge, LayerCard } from 'kumo-svelte';
+</script>
+
+<LayerCard class="space-y-3">
+  <h2 class="text-lg font-semibold">Databases</h2>
+  <div class="flex items-center justify-between">
+    <span>main-db</span>
+    <Badge variant="success">Active</Badge>
+  </div>
+</LayerCard>
+```
+
+</ComponentSection>
+
+<!-- Examples -->
+
+<ComponentSection>
+
+## Examples
+
+### Basic
+
+A minimal resource list page with title, description, and icon.
+
+<ComponentExample demo="ResourceListBasicDemo" />
+
+### With Usage Sidebar
+
+  Include a sidebar with usage examples or quick start guides.
+
+<ComponentExample demo="ResourceListWithUsageDemo" />
+
+</ComponentSection>
+
+<!-- API Reference -->
+
+<ComponentSection>
+
+## API Reference
+
+  
+    <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">Description</th>
+        </tr>
+      </thead>
+      <tbody>
+        <tr class="border-b border-kumo-hairline">
+          <td class="px-4 py-3 font-mono text-xs">title</td>
+          <td class="px-4 py-3 font-mono text-xs">string</td>
+          <td class="px-4 py-3">Page title displayed at the top</td>
+        </tr>
+        <tr class="border-b border-kumo-hairline">
+          <td class="px-4 py-3 font-mono text-xs">description</td>
+          <td class="px-4 py-3 font-mono text-xs">string</td>
+          <td class="px-4 py-3">Page description below the title</td>
+        </tr>
+        <tr class="border-b border-kumo-hairline">
+          <td class="px-4 py-3 font-mono text-xs">icon</td>
+          <td class="px-4 py-3 font-mono text-xs">Component</td>
+          <td class="px-4 py-3">Icon displayed next to the title</td>
+        </tr>
+        <tr class="border-b border-kumo-hairline">
+          <td class="px-4 py-3 font-mono text-xs">usage</td>
+          <td class="px-4 py-3 font-mono text-xs">Snippet</td>
+          <td class="px-4 py-3">
+            Sidebar content for usage examples or quick start guides
+          </td>
+        </tr>
+        <tr class="border-b border-kumo-hairline">
+          <td class="px-4 py-3 font-mono text-xs">additionalContent</td>
+          <td class="px-4 py-3 font-mono text-xs">Snippet</td>
+          <td class="px-4 py-3">
+            Additional sidebar content (e.g., resources, links)
+          </td>
+        </tr>
+        <tr class="border-b border-kumo-hairline">
+          <td class="px-4 py-3 font-mono text-xs">children</td>
+          <td class="px-4 py-3 font-mono text-xs">Snippet</td>
+          <td class="px-4 py-3">Main content area for the resource list</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">Additional CSS classes</td>
+        </tr>
+      </tbody>
+    </table>
+
+</ComponentSection>

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

@@ -0,0 +1,13 @@
+---
+title: "Changelog"
+description: "Release history for Kumo."
+---
+
+<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>
+

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

@@ -0,0 +1,125 @@
+---
+title: "Charts"
+description: "Charts built on ECharts."
+sourceFile: "components/chart"
+headings:
+  - depth: 2
+    slug: "available-charts"
+    text: "Available Charts"
+  - depth: 2
+    slug: "color-system"
+    text: "Color System"
+  - depth: 2
+    slug: "legend"
+    text: "Legend"
+  - depth: 3
+    slug: "largeitem"
+    text: "LargeItem"
+  - depth: 3
+    slug: "smallitem"
+    text: "SmallItem"
+---
+
+<script>
+  import ChartCard from '$lib/docs/ChartCard.svelte';
+  import ComponentExample from '$lib/docs/ComponentExample.svelte';
+  import ComponentSection from '$lib/docs/ComponentSection.svelte';
+</script>
+
+
+<ComponentSection>
+
+<p class="mb-4">
+  Chart components are built on ECharts. Install it as a dependency:
+</p>
+
+```bash
+npm install echarts
+```
+
+<p class="my-4">
+For optimal bundle size, import only the ECharts components you need. The
+examples below show the minimum required imports for our use cases.
+</p>
+
+```ts
+import * as echarts from "echarts/core";
+import { BarChart, LineChart, PieChart } from "echarts/charts";
+import {
+  AriaComponent,
+  AxisPointerComponent,
+  BrushComponent,
+  GridComponent,
+  TooltipComponent,
+} from "echarts/components";
+import { CanvasRenderer } from "echarts/renderers";
+
+echarts.use([
+  BarChart,
+  LineChart,
+  PieChart,
+  AxisPointerComponent,
+  BrushComponent,
+  GridComponent,
+  TooltipComponent,
+  CanvasRenderer,
+  AriaComponent,
+]);
+```
+
+</ComponentSection>
+
+<ComponentSection>
+
+## Available Charts
+
+<div class="grid grid-cols-1 gap-4 sm:grid-cols-2">
+  <ChartCard
+    title="Timeseries Chart"
+    description="A specialized chart for displaying time-based data."
+    href="/charts/timeseries"
+    demo="TimeseriesChartPreviewDemo"
+  />
+
+  <ChartCard
+    title="Custom Chart"
+    description="Examples like pie charts."
+    href="/charts/custom"
+    demo="PieChartPreviewDemo"
+  />
+</div>
+
+</ComponentSection>
+
+<ComponentSection>
+
+## Color System
+
+<ChartCard
+  title="Color Palette"
+  description="Information about our color system."
+  href="/charts/colors"
+/>
+
+</ComponentSection>
+
+<ComponentSection>
+
+## Legend
+
+<p class="mb-6">
+  Use <code>LegendItem</code> to display chart series information with color
+  indicators.
+</p>
+
+### LargeItem
+
+<ComponentExample demo="LegendDefaultDemo" />
+
+### SmallItem
+
+<ComponentExample demo="LegendCompactDemo" />
+
+</ComponentSection>
+
+<ComponentExample demo="ChartExampleDemo" />

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

@@ -0,0 +1,81 @@
+---
+title: "Chart Colors"
+description: "Semantic and categorical color tokens for Cloudflare dashboard charts."
+sourceFile: "components/chart/Color.ts"
+---
+
+<script>
+  import ComponentExample from '$lib/docs/ComponentExample.svelte';
+</script>
+
+
+Chart colors in Kumo are split into three systems — **semantic** tokens for data with inherent
+polarity, a **categorical** palette for nominal series and a **sequential** scale for density encoding. Using the right system for the data type is the most important color decision in a chart.
+
+## Color systems
+
+<div class="mb-6">
+Charts in the dashboard serve different jobs, so color is not one-size-fits-all.
+To avoid misreading data, we use different color systems based on the data task.
+</div>
+
+<ComponentExample demo="ChartColorSystemsDemo" />
+
+## Semantic tokens
+
+<div class="mb-6">
+Semantic chart colors should be used when the data has inherent polarity, i.e. status, severity and health data. Semantic colors communicate to the user that this data needs their attention and an action might be required.
+
+Semantic chart colors are derived from our existing badge/status semantic tokens so meaning stays consistent across components and contexts. We intentionally adjust hue/chroma for charts to be less visually aggressive than badges to reduce visual fatigue and false urgency.
+</div>
+
+<div class="mb-6 flex flex-col gap-6">
+<ComponentExample demo="SemanticColorsDemo" />
+<ComponentExample demo="CategoricalBarChartDemo" />
+</div>
+
+## Categorical palette
+
+<div class="mb-6">
+Use the categorical palette when the data has no inherent polarity. The palette is ordered for maximum perceptual distance between adjacent slots to ensure it's CVD friendly and the data is easily distinguishable.
+</div>
+
+<div class="mb-6">
+<ComponentExample demo="CategoricalColorsDemo" />
+</div>
+
+<div class="text-kumo-info bg-kumo-info-tint/50 rounded-lg py-1 px-4 ring ring-kumo-info mb-12">
+  We reduced categorical tokens from 16 (8 hues x 2 lightness variants) to 5 because most charts intentionally surface only top categories at once (commonly 5). When a chart needs more than 5 series it should cycle those tokens with modulo (color = tokens[i % 5]) for consistent, predictable styling.
+</div>
+
+<div class="my-4">
+Categorical colors are tested using a CVD simulator to ensure they remain distinguishable for users with color vision deficiency. Here's an example of what the categorical colors might look like to someone with deuteranopia.
+</div>
+
+<div class="mb-6 flex flex-col gap-8">
+<ComponentExample demo="CategoricalCvdDemo" />
+<ComponentExample demo="CategoricalDonutChartDemo" />
+<ComponentExample demo="CategoricalLineChartDemo" />
+
+<div class="text-kumo-info bg-kumo-info-tint/50 rounded-lg py-1 px-4 ring ring-kumo-info mb-6">
+  <span class="font-semibold">Color alone should not be used to convey information.</span> When implementing line charts, ensure that you're using patterns (e.g. dashes/dots) on top of the color palette to differentiate between data points. Since dots and dashes appear lighter, we avoid pairing them with light colors since those lines can fade out.
+</div>
+</div>
+
+## Sequential scale
+
+<div class="mb-6">
+A 5-step single-hue scale for encoding **density** — use when a single metric varies in
+magnitude across a set of values and color intensity should reinforce that magnitude.
+Common uses: choropleth maps (traffic volume by country), heatmaps, and histogram fills.
+The sequential scale is not appropriate for categorical series differentiation — use the
+categorical palette for that.
+
+Darker steps encode higher values in light mode; lighter steps encode higher values in
+dark mode so the most prominent color always corresponds to the highest magnitude.
+</div>
+
+<div class="mb-6 flex flex-col gap-6">
+<ComponentExample demo="SequentialColorsDemo" />
+<ComponentExample demo="SequentialHeatmapDemo" />
+</div>