@kubex/zinc 1.0.106 → 1.0.108

package/docs/pages/getting-started/shimmer-text.md

@@ -0,0 +1,81 @@
+---
+meta:
+  title: Shimmer Text
+  description: A global utility class that applies an animated shimmer sweep to text, suitable for loading, processing, or "thinking" states.
+---
+
+# Shimmer Text
+
+`shimmer-text` is a global utility class that animates a horizontal highlight sweep across text colour. Use it to convey an in-progress state — AI generation, background processing, or any "working on it" indicator.
+
+The class works on any element with text content, including inside Zinc components. Colour variants mirror the standard Zinc palette: `zn-primary`, `zn-accent`, `zn-info`, `zn-success`, `zn-warning`, `zn-error`.
+
+When `prefers-reduced-motion: reduce` is set, the animation is suppressed and the text falls back to a solid colour matching the chosen variant.
+
+## Examples
+
+### Default
+
+```html:preview
+<span class="shimmer-text">Thinking…</span>
+```
+
+### Colour Variants
+
+```html:preview
+<div style="display: flex; flex-direction: column; gap: 8px;">
+  <span class="shimmer-text">Default</span>
+  <span class="shimmer-text zn-primary">Primary</span>
+  <span class="shimmer-text zn-accent">Accent</span>
+  <span class="shimmer-text zn-info">Info</span>
+  <span class="shimmer-text zn-success">Success</span>
+  <span class="shimmer-text zn-warning">Warning</span>
+  <span class="shimmer-text zn-error">Error</span>
+</div>
+```
+
+### Headings and Larger Text
+
+The shimmer scales with whatever `font-size` is on the element, so it can be applied to headings or inline within prose.
+
+```html:preview
+<h2 class="shimmer-text zn-primary" style="margin: 0;">Generating summary…</h2>
+<p style="margin: 8px 0 0;">
+  Please wait while we <span class="shimmer-text zn-info">analyse your data</span>.
+</p>
+```
+
+### Inside Zinc Components
+
+Because `shimmer-text` is a plain class, it composes with any Zinc component that renders slotted text.
+
+```html:preview
+<zn-chip class="shimmer-text zn-accent">Processing</zn-chip>
+```
+
+### Tuning the Sweep
+
+The effect mirrors the Claude CLI's character-level shimmer: a narrow, sharper highlight slides across text rather than a soft gradient wash. The class exposes these CSS custom properties — all sized in `ch` so they scale with the current font size.
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `--shimmer-base` | `rgb(var(--zn-text))` | Resting text colour. |
+| `--shimmer-highlight` | `rgb(var(--zn-text-heading))` | Colour of the spotlight. |
+| `--shimmer-core` | `0.5ch` | Half-width of the solid-colour core of the spotlight. |
+| `--shimmer-spread` | `1.5ch` | Half-width of the full highlight including its fade-out edges. |
+| `--shimmer-duration` | `2s` | Time for one full sweep cycle. |
+
+```html:preview
+<div style="display: flex; flex-direction: column; gap: 6px;">
+  <span class="shimmer-text">Default sweep</span>
+  <span class="shimmer-text" style="--shimmer-duration: 1s;">Faster sweep</span>
+  <span class="shimmer-text" style="--shimmer-duration: 4s;">Slower, gentler sweep</span>
+  <span class="shimmer-text" style="--shimmer-core: 1ch; --shimmer-spread: 3ch;">Wider spotlight</span>
+</div>
+```
+
+The Claude CLI scales its sweep with message length (50ms per character plus 10 characters of offscreen pause on each side). To match that feel in CSS, set `--shimmer-duration` to roughly `(messageCharacters + 20) × 50ms`.
+
+### Reduced Motion
+
+The animation is wrapped in `@media (prefers-reduced-motion: no-preference)`. Users who have requested reduced motion see the static colour variant instead — no configuration required.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubex/zinc",
-  "version": "1.0.106",
+  "version": "1.0.108",
   "description": "A collection of web components for building web applications based off of @shoelace-style/Shoelace",
   "keywords": [
     "web components",
@@ -46,9 +46,8 @@
     "@lit/task": "^1.0.1",
     "@shoelace-style/localize": "^3.2.1",
     "air-datepicker": "^3.5.3",
-    "apexcharts": "^4.5.0",
-    "chart.js": "^4.4.8",
     "composed-offset-position": "^0.0.6",
+    "echarts": "^6.0.0",
     "emoji-mart": "^5.6.0",
     "lit": "^2.7.6",
     "marked": "^18.0.2",
@@ -77,9 +76,9 @@
     "custom-element-vs-code-integration": "^1.5.0",
     "custom-element-vuejs-integration": "^1.4.0",
     "del": "^8.0.0",
-    "esbuild": "^0.25.0",
+    "esbuild": "^0.27.7",
     "esbuild-plugin-replace": "^1.4.0",
-    "esbuild-sass-plugin": "^3.3.1",
+    "esbuild-sass-plugin": "^3.7.0",
     "eslint": "^8.57.1",
     "eslint-plugin-chai-expect": "^3.1.0",
     "eslint-plugin-chai-friendly": "^0.7.2",
@@ -94,7 +93,7 @@
     "jsdom": "^26.0.0",
     "lodash": "^4.17.21",
     "lunr": "^2.3.9",
-    "markdown-it": "^14.1.0",
+    "markdown-it": "^14.1.1",
     "markdown-it-container": "^4.0.0",
     "markdown-it-ins": "^4.0.0",
     "markdown-it-kbd": "^2.2.2",

package/scss/shared/index.scss

@@ -2,6 +2,7 @@
 @forward "layout";
 @forward "divide";
 @forward "nav";
+@forward "shimmer";
 
 
 // Need to remove the below from zinc, or have nice defaults that don't mess everything up

package/scss/shared/shimmer.scss

@@ -0,0 +1,98 @@
+
+@keyframes shimmer-text-sweep {
+  0% {
+    background-position: 100% center;
+  }
+  100% {
+    background-position: 0% center;
+  }
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .shimmer-text {
+    --shimmer-base: rgb(var(--zn-text));
+    --shimmer-highlight: rgb(var(--zn-text-heading));
+    --shimmer-core: 0.5ch;
+    --shimmer-spread: 1.5ch;
+    --shimmer-duration: 1.5s;
+
+    display: inline-block;
+    width: fit-content;
+    max-width: 100%;
+    background-image:
+      linear-gradient(
+        90deg,
+        transparent calc(50% - var(--shimmer-spread)),
+        var(--shimmer-highlight) calc(50% - var(--shimmer-core)),
+        var(--shimmer-highlight) calc(50% + var(--shimmer-core)),
+        transparent calc(50% + var(--shimmer-spread))
+      ),
+      linear-gradient(var(--shimmer-base), var(--shimmer-base));
+    background-size: 250% 100%, auto;
+    background-clip: text;
+    -webkit-background-clip: text;
+    -webkit-text-fill-color: transparent !important;
+    color: transparent !important;
+    animation: var(--shimmer-duration) linear infinite shimmer-text-sweep;
+
+    &.zn-error {
+      --shimmer-base: rgb(var(--zn-color-error));
+      --shimmer-highlight: color-mix(in srgb, rgb(var(--zn-color-error)) 55%, white);
+    }
+
+    &.zn-success {
+      --shimmer-base: rgb(var(--zn-color-success));
+      --shimmer-highlight: color-mix(in srgb, rgb(var(--zn-color-success)) 55%, white);
+    }
+
+    &.zn-info {
+      --shimmer-base: rgb(var(--zn-color-info));
+      --shimmer-highlight: color-mix(in srgb, rgb(var(--zn-color-info)) 55%, white);
+    }
+
+    &.zn-warning {
+      --shimmer-base: rgb(var(--zn-color-warning));
+      --shimmer-highlight: color-mix(in srgb, rgb(var(--zn-color-warning)) 55%, white);
+    }
+
+    &.zn-primary {
+      --shimmer-base: rgb(var(--zn-primary));
+      --shimmer-highlight: color-mix(in srgb, rgb(var(--zn-primary)) 55%, white);
+    }
+
+    &.zn-accent {
+      --shimmer-base: rgb(var(--zn-accent));
+      --shimmer-highlight: color-mix(in srgb, rgb(var(--zn-accent)) 55%, white);
+    }
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .shimmer-text {
+    color: rgb(var(--zn-text));
+
+    &.zn-error {
+      color: rgb(var(--zn-color-error)) !important;
+    }
+
+    &.zn-success {
+      color: rgb(var(--zn-color-success)) !important;
+    }
+
+    &.zn-info {
+      color: rgb(var(--zn-color-info)) !important;
+    }
+
+    &.zn-warning {
+      color: rgb(var(--zn-color-warning)) !important;
+    }
+
+    &.zn-primary {
+      color: rgb(var(--zn-primary)) !important;
+    }
+
+    &.zn-accent {
+      color: rgb(var(--zn-accent)) !important;
+    }
+  }
+}

package/src/components/chart/builders.test.ts

@@ -0,0 +1,211 @@
+/* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-assignment, @typescript-eslint/no-unsafe-return, @typescript-eslint/no-unsafe-call */
+import {
+  buildAreaOption,
+  buildBarOption,
+  type BuilderProps,
+  buildLineOption,
+  buildSankeyOption,
+} from './builders';
+import { expect } from '@open-wc/testing';
+
+const baseProps: BuilderProps = {
+  type: 'bar',
+  data: [{ name: 'Sales', data: [10, 20, 30] }],
+  categories: ['Q1', 'Q2', 'Q3'],
+  stacked: false,
+  enableAnimations: false,
+  datapointSize: 1,
+  theme: 'light',
+};
+
+describe('buildBarOption', () => {
+  it('maps a single series into bar type with categories', () => {
+    const opt = buildBarOption(baseProps);
+    expect(opt.series).to.have.lengthOf(1);
+    expect((opt.series as any[])[0].type).to.equal('bar');
+    expect((opt.series as any[])[0].name).to.equal('Sales');
+    expect((opt.series as any[])[0].data).to.deep.equal([10, 20, 30]);
+    expect((opt.xAxis as any).type).to.equal('category');
+    expect((opt.xAxis as any).data).to.deep.equal(['Q1', 'Q2', 'Q3']);
+  });
+
+  it('applies stacking when stacked=true', () => {
+    const opt = buildBarOption({
+      ...baseProps,
+      stacked: true,
+      data: [
+        { name: 'A', data: [1, 2] },
+        { name: 'B', data: [3, 4] },
+      ],
+    });
+    expect((opt.series as any[])[0].stack).to.equal('total');
+    expect((opt.series as any[])[1].stack).to.equal('total');
+  });
+
+  it('does not stack when stacked=false', () => {
+    const opt = buildBarOption({
+      ...baseProps,
+      data: [
+        { name: 'A', data: [1, 2] },
+        { name: 'B', data: [3, 4] },
+      ],
+    });
+    expect((opt.series as any[])[0].stack).to.be.undefined;
+  });
+
+  it('appends y-axis suffix via formatter', () => {
+    const opt = buildBarOption({ ...baseProps, yAxisAppend: '%' });
+    const formatter = ((opt.yAxis as any).axisLabel.formatter) as (v: number) => string;
+    expect(formatter(42)).to.equal('42%');
+  });
+
+  it('maps per-series color to itemStyle.color', () => {
+    const opt = buildBarOption({
+      ...baseProps,
+      data: [{ name: 'Sales', data: [1, 2, 3], color: '#ff0000' }],
+    });
+    expect((opt.series as any[])[0].itemStyle.color).to.equal('#ff0000');
+  });
+
+  it('maps colors array to option.color', () => {
+    const opt = buildBarOption({ ...baseProps, colors: ['#abc', '#def'] });
+    expect(opt.color).to.deep.equal(['#abc', '#def']);
+  });
+
+  it('disables animation by default', () => {
+    const opt = buildBarOption(baseProps);
+    expect(opt.animation).to.equal(false);
+  });
+
+  it('enables animation when enableAnimations=true', () => {
+    const opt = buildBarOption({ ...baseProps, enableAnimations: true });
+    expect(opt.animation).to.equal(true);
+  });
+});
+
+describe('buildLineOption', () => {
+  const baseLineProps: BuilderProps = {
+    type: 'line',
+    data: [{ name: 'Revenue', data: [10, 20, 30] }],
+    categories: ['Jan', 'Feb', 'Mar'],
+    stacked: false,
+    enableAnimations: false,
+    datapointSize: 3,
+    theme: 'light',
+  };
+
+  it('maps a series to line type', () => {
+    const opt = buildLineOption(baseLineProps);
+    expect((opt.series as any[])[0].type).to.equal('line');
+  });
+
+  it('applies symbolSize from datapointSize', () => {
+    const opt = buildLineOption(baseLineProps);
+    expect((opt.series as any[])[0].symbolSize).to.equal(3);
+  });
+
+  it('uses datetime x-axis when xAxisType=datetime', () => {
+    const opt = buildLineOption({ ...baseLineProps, xAxisType: 'datetime' });
+    expect((opt.xAxis as any).type).to.equal('time');
+  });
+
+  it('does not apply areaStyle for plain line', () => {
+    const opt = buildLineOption(baseLineProps);
+    expect((opt.series as any[])[0].areaStyle).to.be.undefined;
+  });
+});
+
+describe('buildAreaOption', () => {
+  const baseAreaProps: BuilderProps = {
+    type: 'area',
+    data: [{ name: 'Traffic', data: [100, 200, 300] }],
+    categories: ['Mon', 'Tue', 'Wed'],
+    stacked: false,
+    enableAnimations: false,
+    datapointSize: 1,
+    theme: 'light',
+  };
+
+  it('maps a series to line type with areaStyle set', () => {
+    const opt = buildAreaOption(baseAreaProps);
+    expect((opt.series as any[])[0].type).to.equal('line');
+    expect((opt.series as any[])[0].areaStyle).to.be.an('object');
+  });
+
+  it('applies stacking when stacked=true', () => {
+    const opt = buildAreaOption({
+      ...baseAreaProps,
+      stacked: true,
+      data: [
+        { name: 'A', data: [1, 2] },
+        { name: 'B', data: [3, 4] },
+      ],
+    });
+    expect((opt.series as any[])[0].stack).to.equal('total');
+  });
+});
+
+describe('buildSankeyOption', () => {
+  const sankeyProps: BuilderProps = {
+    type: 'sankey',
+    data: [{
+      name: 'Flow',
+      data: [
+        { source: 'A', target: 'B', value: 10 },
+        { source: 'A', target: 'C', value: 5 },
+        { source: 'B', target: 'D', value: 7 },
+      ],
+    }],
+    categories: [],
+    stacked: false,
+    enableAnimations: false,
+    datapointSize: 1,
+    theme: 'light',
+  };
+
+  it('builds one sankey series with links mapped from edges', () => {
+    const opt = buildSankeyOption(sankeyProps);
+    const series = (opt.series as any[])[0];
+    expect(series.type).to.equal('sankey');
+    expect(series.links).to.deep.equal([
+      { source: 'A', target: 'B', value: 10 },
+      { source: 'A', target: 'C', value: 5 },
+      { source: 'B', target: 'D', value: 7 },
+    ]);
+  });
+
+  it('derives unique nodes from edge source/target values', () => {
+    const opt = buildSankeyOption(sankeyProps);
+    const series = (opt.series as any[])[0];
+    const names = series.data.map((n: any) => n.name).sort();
+    expect(names).to.deep.equal(['A', 'B', 'C', 'D']);
+  });
+
+  it('omits xAxis and yAxis (sankey has no cartesian axes)', () => {
+    const opt = buildSankeyOption(sankeyProps);
+    expect(opt.xAxis).to.be.undefined;
+    expect(opt.yAxis).to.be.undefined;
+  });
+
+  it('passes through explicit nodes when provided on the series object', () => {
+    const withNodes = {
+      ...sankeyProps,
+      data: [{
+        name: 'Flow',
+        nodes: [
+          { name: 'A', itemStyle: { color: '#f00' } },
+          { name: 'B' }, { name: 'C' }, { name: 'D' },
+        ],
+        data: sankeyProps.data[0].data,
+      }] as any,
+    };
+    const opt = buildSankeyOption(withNodes);
+    const series = (opt.series as any[])[0];
+    expect(series.data[0]).to.deep.equal({ name: 'A', itemStyle: { color: '#f00' } });
+  });
+
+  it('uses tooltip trigger=item (not axis) for sankey', () => {
+    const opt = buildSankeyOption(sankeyProps);
+    expect((opt.tooltip as any).trigger).to.equal('item');
+  });
+});

package/src/components/chart/builders.ts

@@ -0,0 +1,221 @@
+// src/components/chart/builders.ts
+import type { EChartsOption } from 'echarts';
+
+export type ChartType = 'area' | 'bar' | 'line' | 'sankey';
+
+export interface SeriesItem {
+  name: string;
+  data: any[];
+  color?: string;
+}
+
+export interface SankeyEdge {
+  source: string;
+  target: string;
+  value: number;
+}
+
+export interface BuilderProps {
+  type: ChartType;
+  data: SeriesItem[];
+  categories: string[];
+  xAxisType?: 'datetime' | 'category' | 'numeric';
+  yAxisAppend?: string;
+  stacked: boolean;
+  enableAnimations: boolean | number;
+  datapointSize: number;
+  colors?: string[];
+  theme: 'light' | 'dark';
+  smooth?: boolean;
+  scale?: boolean | number;
+  textColor?: string;
+  borderColor?: string;
+}
+
+function commonOption(props: BuilderProps): EChartsOption {
+  const fallback = props.theme === 'dark' ? 'rgb(161, 161, 170)' : 'rgb(113, 113, 122)';
+  const textColor = props.textColor ?? fallback;
+  const animEnabled = props.enableAnimations !== false && props.enableAnimations !== 0;
+  const animDuration = typeof props.enableAnimations === 'number' ? props.enableAnimations : 1500;
+  return {
+    animation: animEnabled,
+    animationDuration: animDuration,
+    animationEasing: 'cubicOut',
+    ...(props.colors ? { color: props.colors } : {}),
+    textStyle: { color: textColor },
+    tooltip: {
+      trigger: 'axis',
+      valueFormatter: props.yAxisAppend
+        ? (v: number | string) => `${v}${props.yAxisAppend}`
+        : undefined,
+    },
+    legend: {
+      top: 0,
+      right: 0,
+      icon: 'circle',
+      textStyle: { color: textColor },
+    },
+    grid: {
+      left: 40,
+      right: 20,
+      top: 40,
+      bottom: 30,
+    },
+  };
+}
+
+function hasNoData(data: SeriesItem[]): boolean {
+  return data.length === 0 || data.every((s) => !s.data || s.data.length === 0);
+}
+
+function buildYAxis(props: BuilderProps) {
+  const emptyOpts = hasNoData(props.data) ? { min: 0, max: 6 } : {};
+  const scaleOpts = props.scale
+    ? {
+        scale: true,
+        ...(typeof props.scale === 'number'
+          ? { boundaryGap: [`${props.scale}%`, `${props.scale}%`] as [string, string] }
+          : {}),
+      }
+    : {};
+  const splitLineOpts = props.borderColor
+    ? { splitLine: { lineStyle: { color: props.borderColor } } }
+    : {};
+  return {
+    type: 'value' as const,
+    ...splitLineOpts,
+    ...emptyOpts,
+    ...scaleOpts,
+    axisLabel: props.yAxisAppend
+      ? { formatter: (v: number) => `${v}${props.yAxisAppend}` }
+      : {},
+  };
+}
+
+function buildXAxis(props: BuilderProps, edgeToEdge = false) {
+  const axisLineOpts = props.borderColor
+    ? { axisLine: { lineStyle: { color: props.borderColor } } }
+    : {};
+  if (props.xAxisType === 'datetime') return { type: 'time' as const, ...axisLineOpts };
+  if (props.xAxisType === 'numeric') return { type: 'value' as const, ...axisLineOpts };
+  return {
+    type: 'category' as const,
+    data: props.categories,
+    ...(edgeToEdge ? { boundaryGap: false } : {}),
+    ...axisLineOpts,
+  };
+}
+
+/* eslint-disable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-return */
+function normalizeData(data: any[]): any[] {
+  return data.map((d: any) => {
+    if (d && typeof d === 'object' && !Array.isArray(d) && 'x' in d && 'y' in d) {
+      return [d.x, d.y];
+    }
+    return d;
+  });
+}
+/* eslint-enable @typescript-eslint/no-unsafe-member-access, @typescript-eslint/no-unsafe-return */
+
+function seriesFromProps(
+  props: BuilderProps,
+  seriesType: 'bar' | 'line',
+  extra: (s: SeriesItem) => Record<string, unknown> = () => ({}),
+) {
+  return props.data.map((s) => ({
+    type: seriesType,
+    name: s.name,
+    data: normalizeData(s.data),
+    ...(s.color ? { itemStyle: { color: s.color } } : {}),
+    ...(props.stacked ? { stack: 'total' } : {}),
+    ...(props.enableAnimations !== false && props.enableAnimations !== 0 && seriesType === 'bar'
+      ? { animationDelay: (idx: number) => idx * 50 }
+      : {}),
+    ...extra(s),
+  }));
+}
+
+export function buildBarOption(props: BuilderProps): EChartsOption {
+  return {
+    ...commonOption(props),
+    xAxis: buildXAxis(props),
+    yAxis: buildYAxis(props),
+    series: seriesFromProps(props, 'bar'),
+  };
+}
+
+export function buildLineOption(props: BuilderProps): EChartsOption {
+  return {
+    ...commonOption(props),
+    xAxis: buildXAxis(props, true),
+    yAxis: buildYAxis(props),
+    series: seriesFromProps(props, 'line', () => ({
+      symbolSize: props.datapointSize,
+      smooth: props.smooth,
+    })),
+  };
+}
+
+export function buildAreaOption(props: BuilderProps): EChartsOption {
+  return {
+    ...commonOption(props),
+    xAxis: buildXAxis(props, true),
+    yAxis: buildYAxis(props),
+    series: seriesFromProps(props, 'line', () => ({
+      symbolSize: props.datapointSize,
+      smooth: props.smooth,
+      areaStyle: { opacity: 0.1 },
+    })),
+  };
+}
+
+function deriveNodes(edges: SankeyEdge[]): { name: string }[] {
+  const seen = new Set<string>();
+  const nodes: { name: string }[] = [];
+  for (const edge of edges) {
+    if (!seen.has(edge.source)) {
+      seen.add(edge.source);
+      nodes.push({ name: edge.source });
+    }
+    if (!seen.has(edge.target)) {
+      seen.add(edge.target);
+      nodes.push({ name: edge.target });
+    }
+  }
+  return nodes;
+}
+
+export function buildSankeyOption(props: BuilderProps): EChartsOption {
+  const first = props.data[0] ?? { name: '', data: [] };
+  const edges = (first.data ?? []) as SankeyEdge[];
+  const explicitNodes = (first as { nodes?: { name: string }[] }).nodes;
+  const nodes = explicitNodes ?? deriveNodes(edges);
+  const fallback = props.theme === 'dark' ? 'rgb(161, 161, 170)' : 'rgb(113, 113, 122)';
+  const textColor = props.textColor ?? fallback;
+
+  const animEnabled = props.enableAnimations !== false && props.enableAnimations !== 0;
+  const animDuration = typeof props.enableAnimations === 'number' ? props.enableAnimations : 1500;
+  return {
+    animation: animEnabled,
+    animationDuration: animDuration,
+    animationEasing: 'cubicOut',
+    ...(props.colors ? { color: props.colors } : {}),
+    textStyle: { color: textColor },
+    tooltip: { trigger: 'item' },
+    series: [{
+      type: 'sankey',
+      name: first.name,
+      data: nodes,
+      links: edges,
+      label: {
+        color: textColor,
+        textBorderWidth: 0,
+      },
+      lineStyle: {
+        color: 'source',
+        opacity: props.theme === 'dark' ? 0.4 : 0.3,
+      },
+      emphasis: { focus: 'adjacency' },
+    }],
+  };
+}