slexkit 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -2,6 +2,58 @@
 
 All notable changes to SlexKit.
 
+## v0.3.0 - Examples overhaul with component audit and i18n
+
+### Added
+- Example gallery: 17 high-quality examples organized by usage scenario (Getting Started, Calculators, Data Browsing, Dashboards, Config Wizards, Decision Support, Platform Features)
+- English translations for all 17 example pages
+- `toolhost-demo`: real `renderToolCall` API with chat-style conversation UI
+- Example rendering infrastructure: `site/routes/examples.js`, `site/pages/examples.slex.js`, `site/data/examples.js`
+- Content discovery: `site/data/content-discovery.js` with locale fallback and allowed-slug filtering
+- `site/data/content-discovery.js`: `discoverExampleMarkdown()` with per-locale discovery
+- SEO metadata for example pages
+- `examples/minimal-cdn/index.html`: zero-build CDN usage example
+- Formula component (`src/components/svelte/content/Formula.svelte`) with KaTeX rendering
+- `src/engine/capabilities.ts`: structured capability docs for AI agents
+- `src/engine/validation.ts`: SPEC contract validation for component specs
+- `src/engine/stdlib.ts`: standard library with `math.clamp`, `math.safeDivide`, and other utilities
+- `src/engine/sandbox-runner.ts`: sandbox runner for secure runtime
+- Component state eval context shadowing test suite (`component-state-shadowing.test.ts`)
+- Collapsible and Callout double-rendering regression tests
+- Slider component name shadowing regression test
+- Tests for content, playground, select, tabs, slider, disclosure, feedback, policy-api
+
+### Changed
+- Examples reduced from 64 to 17 high-quality examples, organized by user story
+- Example source locale: `zh-CN` (with `en-US` translations)
+- `renderChildren` (`helpers.ts`) now clears existing content when children are present
+- Switch component now accepts `checked`/`value` props for initialization consistency with Checkbox
+- Site UI: DocsShell, DocRail, router, shell improvements
+- Components: Input, Select, Tabs, Table, PlaygroundMarkdown refinements
+- CSS: theme-shadcn, text-input, docs-shell styling updates
+- MCP: enhanced with structured capability docs
+
+### Fixed
+- Eval context shadowing: component names `g` and `api` no longer overwrite reserved context keys
+- `renderChildren` double rendering in Collapsible and Callout
+- Voltage divider summary typo ("输入输入电压")
+- Salary calculator fallback numbers to match actual calculator output
+- Tabs-and-branching: title and length conversion mismatch
+- 4 pre-existing test failures (ai-docs, page-structure, theme, markdown-content)
+- Toolhost test: added setup import to fix `document is not defined`
+- Badge stretching in grid layout
+- Project-dashboard syntax error
+- Salary-calculator rate configuration
+
+### Removed
+- 47 low-quality/duplicate examples (reduced from 64 to 17)
+- Dead "Fallback" copywriting from all example files
+- Post-slex explanatory text from example files
+- Unused `DialogShell.svelte` component
+- Orphaned `test-if` example directory
+- Agent-generated `docs/compose` planning files
+- Temporary `screenshot-*.png` files
+
 ## v0.2.0 - First public release
 
 ### Added

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2026 SlexKit
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) 2026 SlexKit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/ai/llms-authoring.txt

@@ -7,6 +7,7 @@ SlexKit's agent-readable source is Markdown with explicit `slex` fences. Do not
 - Emit explicit `slex` fenced code blocks for display-oriented interactive UI.
 - Use a Slex expression envelope: `slex`, `namespace`, `g`, and `layout`.
 - Put mutable state and helper functions in `g`; put component structure in `layout`.
+- Use `std.*` for common calculations, formatting, units, and small statistics.
 - Use component keys in `type:identifier` form, such as `card:summary`.
 - Use `$` read-pipes for dynamic props and `on*` write-pipes for event handlers.
 - Include readable Markdown fallback text after the fence.
@@ -18,6 +19,7 @@ SlexKit's agent-readable source is Markdown with explicit `slex` fences. Do not
 - Do not ask hosts to scan plain JavaScript, JSON, or untagged code blocks.
 - Do not wrap ordinary status cards or summaries in ToolHost.
 - Do not bypass the sandbox for untrusted source.
+- Do not use native `fetch`, `XMLHttpRequest`, `WebSocket`, `setTimeout`, or `requestAnimationFrame` in secure mode; use policy-gated `api.*` instead.
 - Do not invent `.mdx` routes for SlexKit docs.
 
 ## Display UI Example

package/dist/ai/llms-capabilities.txt

@@ -0,0 +1,126 @@
+# SlexKit Capabilities for LLMs
+
+Use `std.*` for pure deterministic calculations and formatting. Use `api.*` only for host-injected or secure-runtime capabilities that may require policy.
+
+## Expression Context
+
+- `g` (always): Reactive state proxy.
+- `std` (always): Pure deterministic SlexKit standard library.
+- `api` (host-injected): Host or secure runtime capability object.
+- `$event` (event handlers): Event payload for on* handlers.
+- `$item` ($for): Current array item.
+- `$index` ($for): Current item index.
+- `$key` ($for): Current item key.
+
+## std.math
+
+Small numeric helpers for common interactive calculations.
+
+- `std.math.clamp(value, min, max)`: Clamp a number into a range. Example: `std.math.clamp(g.score, 0, 100)`
+- `std.math.round(value, digits = 0)`: Round with a fixed number of decimal digits. Example: `std.math.round(g.latency, 1)`
+- `std.math.safeDivide(numerator, denominator, fallback = 0)`: Divide with a fallback for zero or invalid denominators. Example: `std.math.safeDivide(g.used, g.total, 0)`
+- `std.math.percent(part, total, digits = 1)`: Return part / total as a percentage number. Example: `std.math.percent(g.done, g.total, 1)`
+- `std.math.lerp(start, end, t)`: Linear interpolation. Example: `std.math.lerp(0, 100, g.progress)`
+
+## std.stats
+
+Finite-number aggregations for arrays.
+
+- `std.stats.sum(values)`: Sum finite numeric values. Empty arrays return 0. Example: `std.stats.sum(g.samples)`
+- `std.stats.mean(values)`: Average finite numeric values. Empty arrays return NaN. Example: `std.stats.mean(g.samples)`
+- `std.stats.min(values)`: Minimum finite numeric value. Empty arrays return NaN. Example: `std.stats.min(g.samples)`
+- `std.stats.max(values)`: Maximum finite numeric value. Empty arrays return NaN. Example: `std.stats.max(g.samples)`
+- `std.stats.median(values)`: Median finite numeric value. Empty arrays return NaN. Example: `std.stats.median(g.samples)`
+
+## std.format
+
+Deterministic display formatting with en-US defaults.
+
+- `std.format.fixed(value, digits = 2)`: Format a number with fixed decimal places. Example: `std.format.fixed(g.voltage, 3)`
+- `std.format.number(value, digits = 0, locale = 'en-US')`: Locale number formatting. Example: `std.format.number(g.requests)`
+- `std.format.compact(value, digits = 1, locale = 'en-US')`: Compact number formatting. Example: `std.format.compact(g.users)`
+- `std.format.percent(ratio, digits = 1)`: Format a ratio as a percentage string. Example: `std.format.percent(g.done / g.total, 1)`
+- `std.format.currency(value, currency = 'USD', locale = 'en-US')`: Format a currency value. Example: `std.format.currency(g.revenue, 'USD')`
+
+## std.units
+
+Small unit display helpers for common dashboards.
+
+- `std.units.withUnit(value, unit, digits = 2)`: Format a value with a unit suffix. Example: `std.units.withUnit(g.power, 'W', 1)`
+- `std.units.bytes(value, digits = 1)`: Format bytes as B, KB, MB, GB, TB, or PB. Example: `std.units.bytes(g.payloadBytes)`
+- `std.units.duration(ms, digits = 1)`: Format milliseconds as ms, s, min, or h. Example: `std.units.duration(g.elapsedMs)`
+- `std.units.si(value, unit = '', digits = 2)`: Format with SI prefixes. Example: `std.units.si(g.frequency, 'Hz', 2)`
+
+## Policy-Gated Runtime API
+
+- `api.get(url, options)` (network, secure default: denied): Policy-gated GET request.
+- `api.post(url, body, options)` (network, secure default: denied): Policy-gated POST request.
+- `api.fetch(url, options)` (network, secure default: denied): Policy-gated GET or POST request.
+- `api.setTimeout(fn, ms)` (timer, secure default: denied): Policy-gated timeout.
+- `api.clearTimeout(id)` (timer, secure default: denied): Clear a policy-gated timeout.
+- `api.setInterval(fn, ms)` (timer, secure default: denied): Policy-gated interval.
+- `api.clearInterval(id)` (timer, secure default: denied): Clear a policy-gated interval.
+- `api.raf(fn)` (animation, secure default: denied): Policy-gated animation frame.
+- `api.cancelRaf(id)` (animation, secure default: denied): Cancel a policy-gated animation frame.
+- `api.createCanvas(width, height)` (canvas, secure default: denied): Create a policy-counted canvas.
+- `api.getCanvasContext(canvas, contextId, options)` (canvas, secure default: denied): Get a policy-checked canvas context.
+- `api.onDispose(fn)` (lifecycle, secure default: available): Register runtime cleanup.
+- `api.now()` (lifecycle, secure default: available): Runtime clock.
+- `api.isTimeoutError(error)` (diagnostics, secure default: available): Check timeout errors.
+- `api.isNetworkError(error)` (diagnostics, secure default: available): Check network errors.
+- `api.isPolicyError(error)` (diagnostics, secure default: available): Check policy errors.
+- `api.errorMessage(error)` (diagnostics, secure default: available): Extract a displayable error message.
+
+Secure mode blocks native `fetch`, `XMLHttpRequest`, `WebSocket`, `setTimeout`, `setInterval`, and `requestAnimationFrame`. Use `api.get`, `api.post`, `api.fetch`, `api.setTimeout`, `api.setInterval`, and `api.raf` when host policy enables them.
+
+## Recipe: Std Calculator
+
+```slex
+{
+  slex: "0.1",
+  namespace: "std_calculator",
+  g: { done: 7, total: 12, samples: [120, 95, 143, 110], bytes: 1536000 },
+  layout: {
+    "card:summary": {
+      title: "Stdlib calculator",
+      "stat:progress": { label: "Progress", "$value": "std.format.percent(std.math.safeDivide(g.done, g.total), 1)" },
+      "stat:average": { label: "Average", "$value": "std.format.fixed(std.stats.mean(g.samples), 1)", unit: "ms" },
+      "stat:payload": { label: "Payload", "$value": "std.units.bytes(g.bytes)" }
+    }
+  }
+}
+```
+
+## Recipe: Secure Network Card
+
+```slex
+{
+  slex: "0.1",
+  namespace: "secure_network_card",
+  g: {
+    status: "idle",
+    async load() {
+      this.status = "loading";
+      try {
+        var result = await api.get("https://api.example.com/status", { credentials: "omit" });
+        this.status = "HTTP " + result.status;
+      } catch (error) {
+        this.status = api.isPolicyError(error) ? "blocked by policy" : api.errorMessage(error);
+      }
+    }
+  },
+  layout: {
+    "card:network": {
+      title: "Secure network card",
+      "button:load": { label: "Load", onclick: "g.load()" },
+      "text:status": { "$text": "g.status" }
+    }
+  }
+}
+```
+
+## Recipe: Timer and Animation Policy
+
+- Timers are disabled in secure mode unless `policy.timer.enabled` is true.
+- Use `api.setTimeout` and `api.setInterval`; do not use native scheduling globals.
+- Animation is disabled unless `policy.animation.enabled` is true; use `api.raf`.

package/dist/ai/llms-components.txt

@@ -2,7 +2,7 @@
 
 Use these components inside Markdown `slex` fences. Raw component docs are ordinary `.md` pages that preserve `slex` examples.
 
-Public component count: 28
+Public component count: 29
 
 ## Disclosure
 
@@ -39,6 +39,12 @@ Public component count: 28
 - [Slider](/docs/components/slider.md): `slider` - Numeric range input.
 - [Switch](/docs/components/switch.md): `switch` - Boolean switch input.
 
+## Display
+
+- [Formula](/docs/components/formula.md): `formula` - Reactive KaTeX formula display.
+- [Stat](/docs/components/stat.md): `stat` - Metric display.
+- [Text](/docs/components/text.md): `text` - Plain text display.
+
 ## Component
 
 - [Icon](/docs/components/icon.md): `icon` - Shared icon field capability.
@@ -52,11 +58,6 @@ Public component count: 28
 - [Progress](/docs/components/progress.md): `progress` - Progress bar.
 - [Toast](/docs/components/toast.md): `toast` - Transient notification.
 
-## Display
-
-- [Stat](/docs/components/stat.md): `stat` - Metric display.
-- [Text](/docs/components/text.md): `text` - Plain text display.
-
 ## Data
 
 - [Table](/docs/components/table.md): `table` - Simple data table.
@@ -265,6 +266,26 @@ No child components.
 
 ---
 
+## Formula API (`formula`)
+
+Category: Display
+Status: ready
+State mode: none
+Since: 0.1.0
+
+### Props
+- `tex` (string; optional; dynamic): KaTeX source to render.
+- `formula` (string; optional; dynamic): Alias for tex.
+- `value` (string; optional; dynamic): Alias for tex.
+- `displayMode` (boolean; optional; static; default: true): Render as display math when true; inline math when false.
+- `display` (boolean; optional; static; default: true): Alias for displayMode.
+- `block` (boolean; optional; static; default: true): Alias for displayMode.
+
+### Children
+No child components.
+
+---
+
 ## Grid API (`grid`)
 
 Category: Layout